It was not as easy as I expected but I found it out. Creating the a django project’s API doc is pretty easy once you know how! Unfortunately there is a bug in the django integrated doc that you can reach via the admin interface by /admin/doc/ but it is also far less complete (if it would entirely work) than what a pydoc offers.
One problem with both tries the django admin doc and the pydoc was that we are using a lot of decorators for view functions. Decorators such as “login_required” or “transaction.commit_on_success” and the doc generators both either ignored those functions or linked wrong (django admin doc).
So I decided I want the real API docs and done, that is what most devs are best familiar with. But to get that you need to fiddle a little bit with the setup of django and export some variables in order to properly make doc generation work. We used epydoc for generating the docs, it throws out the nice frame-based javadoc like view, I find that quite handy.
Here is how it goes:
export PYTHONPATH=$PYTHONPATH:/Users/wolfram/projectname/trunk/- extend the python path so that it also find your project
export DJANGO_SETTINGS_MODULE=projectname.settings- set the required django variable
/Library/Frameworks/Python.framework/Versions/2.4/bin/epydoc --html --parse-only --docformat plaintext re -v projectnamemake epydoc generate the docs
epydoc will create a directory named “html” and put all the docs in there, open the index.html in your browser and you are all fine. Happy doc reading …