Literate Programming — a real solution?
Sphinx is a really popular documentation generator for python, probably due to ease of use and the absolutely gorgeous output it gives.
PyLit is a way to convert python code directly into ReST (the format Sphinx uses) and back.
Sphinx provides indexing, cross reference and other goodies.
Based on these two facts, I think that PyLit and Sphinx are a legitimate literate programming tool for python.
Literate programming allows the author to tell a narrative to explain how a system works, browsing API docs or source code is difficult unless you have a narrative or examples to follow.
The other alternative I looked into was epydoc. Although epydoc does generate excellent API documentation, it doesn’t really provide a narrative, the closest thing to a narrative I see is package or module level documentation.