OpenERP Documentation

How do I build the parts of the documentation from the source code docstrings

Asked by Nick White

I prefer to read the openerp docs from my local machine, so build them using "make html" from a bzr checkout of http://bazaar.launchpad.net/~openerp-community/openobject-doc/trunk/

I expected this to be the same as the http://doc.openerp.com, but it doesn't appear to be. In particular, some content is missing compared to the web site. A good example of this is developer/2_5_Objects_Fields_Methods/methods.html which on my build contains only the initial 3 paragraphs, compared to lots of good class information in the "ORM methods" section.

Isn't http://doc.openerp.com supposed to be built directly from trunk? Why am I not seeing the same docs when I build the docs on my local machine? If it's the case that the bzr trunk doesn't reflect the nature of the latest documentation, that's obviously a Bad Thing.

Thanks.

Question information

Language:
English Edit question
Status:
Solved
For:
OpenERP Documentation Edit question
Assignee:
No assignee Edit question
Solved by:
Don Kirkby
Solved:
Last query:
Last reply:

This question was originally filed as bug #680084.

Revision history for this message
Numérigraphe (numerigraphe) said : 		#1

The section concerning the ORM methods is build from the source code's docstrings I believe.
The rest should be up to date.
Lionel.

Revision history for this message
Nick White (r-launchpad-njw-me-uk) said : 		#2

Ah, great, thanks for letting me know Numérigraphe. It's a relief to know that it isn't because of things just falling out of sink.

How do I build the docs including the source code's docstrings, then? I can't find any documentation on how to do that.

Revision history for this message
Numérigraphe (numerigraphe) said : 		#3

I'm turning your bug into a question so that hopefully someone can shed some light on this.
Lionel Sausin

Revision history for this message
Launchpad Janitor (janitor) said : 		#4

This question was expired because it remained in the 'Open' state without activity for the last 15 days.

Revision history for this message
Nick White (r-launchpad-njw-me-uk) said : 		#5

I'm not overly familiar with launchpad, but it doesn't seem useful to expire this; it's still very much an open question.

Revision history for this message
Launchpad Janitor (janitor) said : 		#6

This question was expired because it remained in the 'Open' state without activity for the last 15 days.

Revision history for this message
Nick White (r-launchpad-njw-me-uk) said : 		#7

See above; this bug ("question") is not resolved.

Revision history for this message
Best Don Kirkby (donkirkby) said : 		#8

There are a few steps required to make the documentation build include the docstrings from the server project:

1. It seems like you need at least version 1.0 of Sphinx. I'm running Ubuntu Lucid, and it currently has an older version. The Sphinx home page said to run "easy_install -U Sphinx" and that worked for me. run "sphinx-build --help" to see what version you have. The Sphinx home page is http://sphinx.pocoo.org
2. You need to have a copy of the OpenERP server code. The web site is built against the trunk version, as far as I know.
3. You need to tweak server/bin/tools/config.py by commenting out the call to config.parse_config() on the last line. Hopefully that will get cleaned up eventually, but for now you either need a second copy of the server just for building the docs from or you need to add and remove this tweak every time you work on the docs.
4. You need to add server/bin to your PYTHONPATH environment variable. The simplest way to do that is to launch make like this:

PYTHONPATH=/path/to/server/bin make html

This is a summary of the advice I got from Olivier Dony. The original discussion is in the archive here:
https://lists.launchpad.net/openerp-doc/msg00146.html

Revision history for this message
Don Kirkby (donkirkby) said : 		#9

I've also added this info to the main documentation site:
http://doc.openerp.com/contribute/08_documentation_process.html#linking-to-docstrings-in-source-code

Revision history for this message
Nick White (r-launchpad-njw-me-uk) said : 		#10

Thanks Don Kirkby, that solved my question.

Revision history for this message
Nick White (r-launchpad-njw-me-uk) said : 		#11

(Wow, launchpad submits comments for me... creepy)

But yes, thanks a lot Don, that's really good to know. And thanks for adding the process to the documentation, too.

I haven't tried this myself yet, but will do quite soon, and will let you know of any problems (though I don't expect to find any).

Keep up the sterling work :-)