Andrew Channels Dexter Pinion

Wherein I write some stuff that you may like to read. Or not, its up to you really.

February 10, 2004

Documenting Python Source Code

I've got this code, which is nearly ready to make its way into the big, wide world, much like someone else. As part of the final tidy up I'm adding docstrings to all of my methods, classes and modules. Then I want to use a tool to generate html documentation from them. I'd like the output to be valid HTML 4.01 or xhtml so that I can control the fonts, colours and text size of the output with my own stylesheet.

I've tried out epydoc, and it looks quite good. But it doesn't appear to be under very active development and there isn't a mailing list to ask. The alternatives look to be HappyDoc, Docutils and Synopsis.

Epydoc works for me, but should I continue to use it or switch to an alternative? Have I missed a Python documentation tool in case Google comes indexing?

Posted by Andy Todd at February 10, 2004 08:44 PM


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

Posted by: simon on February 10, 2004 09:25 PM

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.

Posted by: Ian Bicking on February 10, 2004 11:25 PM

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

Posted by: Brian Lenihan on February 11, 2004 05:11 AM

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.

Posted by: Jeffrey Shell on February 11, 2004 05:28 AM

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?

Posted by: chewie on February 11, 2004 03:48 PM

A simple doc tool is Peter Norvig's py2html, along with his docex, found at:

Posted by: Jeff Sandys on February 11, 2004 05:12 PM

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).

Posted by: Seth Falcon on February 11, 2004 05:28 PM

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.

Posted by: Ian Bicking on February 11, 2004 07:01 PM

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.

Posted by: Clint on February 11, 2004 08:53 PM

I've used epydoc to generate docs for Kiwi -- see -- 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.

Posted by: Christian Reis on February 12, 2004 03:32 AM

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.

Posted by: Chris Armstrong on February 12, 2004 04:21 AM

Doxygen with the Python filter at: does a great job. It will even generate UML class graphs if dot is installed. Sample is at:

Posted by: Kevin Dahlhausen on February 12, 2004 03:04 PM

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

Posted by: Simon Brunning on April 19, 2004 10:03 AM

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.

Posted by: Stefan on November 11, 2004 06:30 AM