Community mailing list archives

community@mail.odoo.com

Re: implementing - gitchangelog to odoo and its modules

by
Cody Kitterman
- 05/23/2016 10:06:40
Gentlemen:

Here's what we're saying: "Help me help you... Help me! help... You! We care...! We want to work with you..."

This is what we get in return:

"But IMHO (and please do not take me wrong)

IF you are a python versed, you should know that those are obvious steps when you compile an sphinx documentation, and the file structure is the basic one.."

Translation: "You must
―and don't take this personally—be an idiot."

The above is as objectively dumb as it is insulting: I can prove it.





Translation: "IF you are a python versed, you should know that " Odoo's documentation != Python's Standards. Sphinx, therefore == GIGO [Garbage in, garbage out]

Odoo's founder knows this. He doesn't deny it, he offers excuses:

"We actually try very hard to educate and inform developers and users; But Odoo is huge and evolving very quickly, so it's not easy. "

Translation: "We actually try very hard... But my project is too big for me, it's getting away from me, and Mr. Hernandez doesn't give a shit... "
 
Members of the Odoo S.A. team know this:
"The business methods of the different modules are usually not well documented. However we do not encourage to write docstring for all the business methods because:
- it is hard to identify the one that really make sense to document
- the logic of such methods can potentially change often and it can be misleading for unmaintained docstring
- it is not published anywhere unlike the ORM methods
"

Translation: Odoo should THINK about implementing SOMETHING LIKE gitchangelog, which AUTOMATES changelogs; Mr. Hernandez doesn't seem to think it's needed, doesn't understand their use, BUT HE WASTED MONEY WRITING SOMETHING "LIKE" IT, and so PERHAPS we should use that.


Respectfully,
Cody Kitterman
Sole Architect behind both the United State Marine Corps' Electronic Personnel Action Request System [EPARS], used by hundreds of thousands of US Marines and dependents, and their Wounded Warrior Tracker. (Between the ages of 17-21, while serving as a LCpl aboard Camp Lejeune)




On Mon, May 23, 2016 at 4:57 AM, Andreas Becker <andi@lisandi.com> wrote:
Hi Robert and those who want to have a local documentation which is not included in an individual Odoo Installation, what actually the post was all about!

do the following:

Make sure you have sphinx installed on your server/computer
$ pip install Sphinx
next run 
$ sphinx-quickstart
this creates a source directory and configures sphinx with some useful stuff.

The sourcefile suffix will be .rst - It will ask you also several other questions.

After you have created your file you can edit it i.e. by using any editor (vi) etc.

close and save your file again

than in the same directory execute
$ make html
if like to get a pdf
$ make latexpdf
last step it need to know where the code is actually

therefore uncomment the line in conf.py before you run 

sys.path.append(os.path.abspath('.'))

if you keep it in the make directory - which is our case the current working directory!

When putting that into an Odoo module we would need to specify the correct path to the documentation and also it would be advised to run
$ sphinx-build [options] sourcedir builddir [filenames]
instead of only 
$ make html
from a current working directory

If you made changes to the documentation (edits etc.) than run
$ make clean
and run 
$ make html
again so that everything gets included properly

go in your directory to 

build/html and click on index.html and you will have the documentation.

This is what would be needed to be visible from the backend or even from the frontend of an individual Odoo installation.

As each Odoo Installation has several modules activated and deactivated it would be great to have a way that only the documentation of the active modules get shown but for developers on the other hand it would be also interesting to see what other modules, even those who have not been included would be available including their documentation.

I suggest in having for that kind of documentation a separate directory which for security reasons also could be blocked and made visible only if you sign in from certain IP addresses. 

For those who secure their sites in other ways it might be interesting to get the documentation of the modules also been visible from the frontend - especially for installations for support purposes this would be interesting I guess. It is great for SEO too by the way!

What would now be very interesting for developers would be actually if also a gitchangelog could be created for all those modules integrated in an installation. As those modules are very often hosted in many different git repositories and some even locked or not reachable there needs to be a routine to check if a changelog is available.

With that a developer and also a user would have a handy individual documentation for each individual odoo installation and he would be able to call it from with his odoo backend and perhaps even be able to search it. This would be much easier than using Google, looking in multiple repositories of github accounts or trying to find answers in the world wide web.

By the way you could include also your own documentation for the user in the same way.



With kind regards,
Mit freundlichen Grüßen,
Con un cordial saludo,
Cordialement,
с сердечным приветом,
เรื่องที่เกี่ยวกับชนิด,
與親切的問候,

 ANDI BECKER

CEO/General Manager LisAndi Co., Ltd.

--------------------------------------------------

LisAndi Co. Ltd., Phuket, Thailand (lisandi.com)
15/21 M.2 Viset Road, Rawai, Muang, Phuket, Thailand 83130

VoIP:   +49 (0)711 50 88788 50
Fax:     +49 (0)711 50 88788 50
Skype:          lisandi
Facebook:     andibecker
Google Talk/Facetime/eMail:  andi@lisandi.com

--------------------------------------------------


On Mon, May 23, 2016 at 1:57 PM, Nhomar Hernandez <nhomar@vauxoo.com> wrote:

On Mon, May 23, 2016 at 1:42 AM, robert rottermann <robert@redcor.ch> wrote:
thanks for confirming my concerns :)
not even this morsel of needed information is there ..

Sorry men.

But IMHO (and please do not take me wrong)

IF you are a python versed, you should know that those are obvious steps when you compile an sphinx documentation, and the file structure is the basic one..:









--
Nhomar Hernandez
CEO Vauxoo.
Twitter: @nhomar
Odoo Gold Partner
Skype: nhomar00 (Envia mail previo no lo superviso siempre).
Móvil Venezuela:
+58 4144110269
Móvil México:
+52 1 4773933942

_______________________________________________
Mailing-List: https://www.odoo.com/groups/community-59
Post to: mailto:community@mail.odoo.com
Unsubscribe: https://www.odoo.com/groups?unsubscribe


_______________________________________________
Mailing-List: https://www.odoo.com/groups/community-59
Post to: mailto:community@mail.odoo.com
Unsubscribe: https://www.odoo.com/groups?unsubscribe