Andrew Channels Dexter Pinion

Well, you could always use 'pydoc -w'.

docutils really isn't what you're looking for, it doesn't really read source and create documentation (maybe it can be made to at the PyCon Sprint [though some hacks exist to do so now]). Twisted Lore is another option, though it involves writing XML/XHTML in your docstrings (I believe), which personally I wouldn't care for. I'd probably choose epydoc for its reST support.

You should also check out the effbot's PythonDoc. The URL is linked to my name.

I'd use epydoc + reST (or plain text). reST is being designed to be the documentation 'standard' for Python, and I've found it to be quite nice to write in. It's not really a code documentation tool on its own though, as Ian's pointed out (I haven't followed development since the 0.3 release, however, and that was a while ago). In any case, epydoc has the nicest output of the tools I've tried so far.

I have to agree with simon. Python docstrings were a god-send after the nightmare of javadoc. docstrings and reST, because of it's simplicity and readability, seems the most Pythonic answer to documenting your modules. pydoc with the '-g' and '-w' options works beautifully for most cases. Remember to keep docstrings short and to the point; they're not meant to contain tutorials or manuals. If you give your method parameters meaningful names, they become somewhat self-documenting. One thing I've found helpful is the doctest module. When docstrings that contain doctests are viewed through pydoc, they simply look like well-documented examples of method use. In actuality, they're module and method test units. How can you go wrong with that?

A simple doc tool is Peter Norvig's py2html, along with his docex, found at: http://aima.cs.berkeley.edu/python/readme.html

I'd say +1 on the epydoc + reST approach. I think reST is easier to read in its unrendered form when compared to alternatives such as epytext. Furthermore, it seems to have the potential to become the standard. PythonDoc loses the contest for me because it is based on comments and not docstrings, however, I like that it parses the code rather than using introspection; In the past I've had some problems with epydoc barfing on certain modules (numeric's MA module IIRC).

Another bonus of something reST-based is that reST is a good tool for writing manuals and stand-alone documentation. For several of my projects I haven't been using docstrings a lot (they don't work well in frameworks), but I use reST for the manual. So it's good to have a format that is powerful enough to produce a good long-format document, as well as the snippets you pull out of docstrings.

Check out AsciiDoc. It's not specifically built for documenting APIs, but because of its simplicity and what looks like an elegant design, may not be difficult to bend accordingly.

http://www.methods.co.nz/asciidoc/

I've used epydoc to generate docs for Kiwi -- see http://www.async.com.br/projects/kiwi/api/ -- and I *really* liked it. Ed, the author, provided great support when I needed it (and did a lot of good work meantime!). I'd definitely recommend it.

Twisted Lore isn't for API docs, Ian. The Twisted project uses epydoc (with several hacks) to generate its API documentation. Twisted Lore is for stuff like HOWTOs, tutorials, and whatever other regular document authoring.

Doxygen with the Python filter at: http://i31www.ira.uka.de/~baas/pydoxy/ does a great job. It will even generate UML class graphs if dot is installed. Sample is at: http://i31www.ira.uka.de/~baas/pydoxy/html/classexample_1_1Demo.html

There was a new Epydoc release in March 2004, so it's not dead after all!

Doxygen is great with class inheritance and collaboration graphs.

But the python filter approach cannot detect member variables. And I think this is hard to solve because python has no member declarations to be parsed.