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.