Iraniblog

Was looking into auto-generated documentation for my python code and came across the following projects: pydoc, epydoc, and sphinx. Pydoc was pretty limited and didn’t output the most useful data. Epydoc is quite easy to use and does a great job at showing all your classes, functions, and variables. And then there was Sphinx. Sphinx is really the end-all and be-all documentation tool. It does a lot and lets you do a lot, BUT you have to put a little time into it. So if the documentation is just for your own purposes, it might not be worth it. If the documentation’s for an open source project, it’s probably worth the fuss, because it’s really not that bad and makes some really good looking docs. My one further point on this, is that the other tools are very limited in scope compared to Sphinx. You use Sphinx as a tool to write documentation outside the documentation in your code. The other tools pretty much strip the doc-strings from your code and make them pretty. Definitely worth looking into Sphinx for any serious open source project.

As an aside, I always wondered what Django used to make their documentation, and now it seems it was Sphinx all along. http://docs.djangoproject.com/en/dev/internals/documentation/

Epydoc: http://epydoc.sourceforge.net/
epydoc --html python_file_1 python_file_2 python_file_3 version -o packrat_docs

Sphinx: http://sphinx.pocoo.org/
By far the nicest of the three tools is Sphinx.
The Python documentation was done using Sphinx: http://docs.python.org/dev/
Sphinx was a little confusing to setup. First off there was a dependancy to jinja2 that really wasn’t spelled out (beyond the errors that came up during install).

So after installing ‘jinja2′ it was as simple as running
sudo easy_install -U Sphinx

pydoc: http://docs.python.org/library/pydoc.html
Command looks something like this:
pydoc -w python_file-1
Seems to want the data to fit a certain setup.