Generating Open ERP docs: the beauty of sphinx

http://toolpart.hu/blog/2011/07/22/generating-open-erp-docs-beauty-sphinx/

At ToolPart Team we always try to document as much of our code as possible. Documentation is present everywhere in our work:

  • we write specifications to our clients
  • we write comments in our code
  • we write yaml test that work as documentation too
  • the description field of our Open ERP addons serve the purpose of documentation
  • etc

Unfortunately, our favourite ERP framework still lacks documentation. As we dive into it more and more, we always found undocumented parts. That last one was its workflow service. So, after understanding it, we documented it.

We decided to document the workflow service using docstring, and to use Sphinx’ autodoc module to add the documentation into the Developers book.

Building the docs is described in the Open ERP Community book. But it wasn’t that easy! We had already a system-wide sphinx installation, while openerp is installed in a virtualenv. Even if we installed sphinx under the virtualenv, it could not import the openerp modules. What goes wrong? We had no idea, but finally figured out.

It’s not enough to have openerp-server, as a Pyton package under your sys.path’s directory. We had to add the openerp-server directory directly using the PYTHONPATH environment variable. This is mentioned in the docs already, but it wasn’t totally clear.

Thus running

PYTHONPATH=~/.virtualenvs/openerp6/lib/python2.6/site-packages/openerp-servermakehtml

Now builds the docs properly.

Advertisements
This entry was posted in Uncategorized. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s