Epydoc and zope

1 July 2007

I have a 30K+ line of code Zope Product with the number of classes you can imagine, may be 150 or 200. Although python is great at helping structure the whole thing, it was time to go beyond this and to involve an automatic documentation tool.

In particular, I have a few big persistent classes whose implementation is split into several files, so it was getting harder to keep track of all the functions of a given class.

I used to use Doxygen in my C++ days, but it's based on a manually written description of functions, while what I really needed was a tool able to extract the structure of the classes and to put things together.

pydoc felt great, but didn't seemed very comfortable with Zope, so I turned to epydoc, having read on the web that, given a few tricks, it worked well with Zope.

It didn't seamlessly for me (under Ubuntu 7). I used zope2.9, out of the box.

Two problems had to be overcame : variations between python versions and gathering together the various Zope Products directories.

Various python version

Zope uses some particular version of python (python2.4 in my case). However, several versions of python are installed to accommodate the various softwares using it. The default version of python is python2.5 in my case. So epydoc runs by default on python2.5, while the right versions of the libraries for my product are under python2.4.

Products and library spreaded in various directory

My Zope Product is installed under a particular Zope Instance. To be able to work, epydoc needs not only to find it, but also the Zope python libraries (common to all instances), some Products specific to this instance, and various support libraries, the right versions.

Also, some modules in my Product addresses other modules in an absolute way (something like import Products.MyProduct.MyModule.MySubModule), to be able to navigate within the hierarchy, so this Products directory must be accessed in one way or another.

To summarize, the hierarchy looks something like this:

/usr/lib/python2.4/site-packages
          .... Various useful python packages
/usr/lib/python2.5/site-packages
          .... The same packages, with a version that'll break under Zope
/usr/lib/zope2.9/lib/python
          ... the Zope core libraries (such as App, AccessControl and so on)
/usr/lib/zope2.9/lib/python/Products
           ... various Zope Products I use
/var/lib/zope2.9/instance/dev/Products
          .... various Products I use inside my own
/var/lib/zope2.9/instance/dev/Products/MyProduct
          .... Here it is !

Extending PYTHONPATH quickly became a nightmare, because of the order the inclusion of the various Products directory.

Putting things together

To make things simple I adopted the lazy way: creating a /tmp/lib directory with symbolic links to the appropriate python library and Zope Products, so things are together in one, easy to point to, place, except the core module.

Now, using python2.4:

PYTHONPATH=/tmp/lib:/usr/lib/zope2.9/lib/python: python2.4 /usr/bin/epydoc -o /tmp/output-dir Products/MyProduct

It worked !

Comments

<comments/>