Python documentation drawback solved: DOH

Saturday, October 29th, 2005

One of my main issues with Python was the terrible documentation. The module reference manual often omitted various methods and other details. It’s even completely down right now.

Turns out though that this problem is quite easily solved by the ‘pydoc’ utility. I’d already used pydoc to generate documentation for my own programs, kind of like javadoc. Turns out though you can also use it on a complete directory, including the modules directory:

[todsah@jib]~/doc/py_ref$ pydoc -w /usr/lib/python2.3/
wrote encodings.base64_codec.html
wrote encodings.html
wrote encodings.aliases.html
wrote email.Generator.html
wrote email.Charset.html
wrote email.Encoders.html
wrote email.Errors.html
wrote logging.html
wrote logging.config.html
wrote logging.handlers.html
...

Drawbacks:

• No index file, apparently.
• Not recursive

Even beter is pydoc’s built-in HTTP server:

[todsah@jib]~$ pydoc -p 10000
pydoc server ready at http://localhost:10000/

Now fire up your browser and point it to the URL mentioned. Presto! A full index of all documentation, generated live from the documentation strings in the various modules.

Well, this sure fixes the documentation drawback. :)