On a fair day in a far away land there was once pydoc, a cunning warrior indeed. Generating docs for distribution wasn't too hard, just a few lines like ...
os.chdir(build_dir)
src_dir = os.path.basename(mymod.__file___)
pydoc.writedocs(src_dir, '%s.' % mymod.__name__)
... or something. But the output is hard to customize. Along came epydoc, which looked to be based loosely on javadoc. Getting over the cringe induced by that latter statement I tried it out anyway and immediately got a headache trying to figure out where my docstrings were ... or how to navigate the frames within frames of whatever I was looking at.
There was also once HappyDoc but I had never tried that one. Somewhere, PythonDoc popped up and I have a vague memory of trying it out and getting a similar epydoc headache ... or being turned off by its javadocness, etc. Let me remind you this is all just one humble, impatient coder's opinion ;)
Then ... there was a very hopeful pudge which aimed to solve a lot of problems (templating, RST formatting) but seemed to break easily if your module did something out of the ordinary. I think we can all agree that generating python docs is hard! Let's hear a round of applause for pudge. Seriously, I tried very hard to use it and it served me well, up to a point. I think I even submitted a patch once.
Now...
I just tried out pydoctor and ... I like it! It seems in early stages yet but it made a very nice navigation out of my fixture module (I'll post that once I add it to the build). A friend of mine tried it out on a module with rST docstrings and reports that this was working nicely too, minus some css tweaks for doctests. Did I mention that it's fast?? The main page has some links to examples of generated API docs.
The link above will also explain how to get it from subversion. Which brings me to a big disclaimer: all observations here are with revision 37310! It also needs twisted and the dev version of Nevow (this wasn't available from easy_install but the link to subversion is on the Nevow page). There was also a confusing warning, something like no epytext found, but that was actually a swallowed ImportError and easy_install epydoc was the necessary fix. Epydoc isn't mandatory, but is an option and I am about to read about epytext now.
This is definitely one to keep an eye on.