It is an API documentation tool for Python, somewhat like Epydoc, Pudge, Endo or HappyDoc.
pydoctor was written to be used by the Twisted project which was using epydoc but was becoming increasingly unhappy with it for various reasons. In addition, development on Epydoc seemed to have halted.
I tried to use most of the tools listed above; Pudge crashed, Endo seemed to depend on the enormous Enthought package and HappyDoc is to all appearances dead as a door-nail. So, when I had a long-ish journey to make I started coding, and a week or so of evenings later with some help from Christopher Armstrong and a few others, had something that was actually useful.
The needs of the twisted project are still the main driving force for pydoctor's development, but it is getting to the point where there's some chance that it is useful for your project too.
pydoctor is probably best suited to documenting a library with a some degree of internal subclassing. It also has support for zope.interface, and can recognise interfaces and classes which implement such interfaces.
pydoctor works by parsing the source code and processing the syntax trees. This has advantages and disadvantages relative to inspecting objects, as Epydoc 2 does.
I'm not especially interested in promoting pydoctor as the be all and end all of API documentation generation. It works for me and it works for Twisted. Maybe it works for you too.
My current (spare time) hacking plans move pydoctor in two directions that AFAIK other documentation generations tools do not go: using Unobtrusive JavaScript to add a level of dynamism to the documentation (sorting methods by line number or method name, for example) and an appserver variant that allows users of the documentation to edit docstrings online.
Michael "mwh" Hudson, PyPy and CPython hacker, with help from Christopher "radix" Armstrong and Jonathan "jml" Lange and advice and ideas from many people who hang out in #twisted on freenode.
I haven't made any proper releases yet, so you have to get it from version control. You have two choices, Bazaar:
bzr get lp:pydoctor pydoctor
Or Subversion:
svn co http://codespeak.net/svn/user/mwh/pydoctor/trunk pydoctor
I do most of my development in the Bazaar branch these days, but the two are kept in sync via the magic of bzr-svn.
If you think you might want to hack on pydoctor, I strongly recommend the Bazaar version. Being able to commit without getting the commit bit off me is very nice :-)
This is a big enough topic to deserve its own page.
It looks like this, which is usually the output of SVN HEAD of pydoctor run on SVN HEAD of Twisted, updated every few days.
I also periodically run pydoctor on Nevow and put the output here, which shows off pydoctor's abilities to do cross-package links.
The output is reasonably simple, clean HTML (it validates!) created from Nevow templates and styled with CSS, so while there's no flexibility in the code yet, it would probably not be that hard to add (this is how pydoctor has been developed in general: rather than try and predict what will be useful, I've tried to keep things reasonably clean and separate to allow rapid implementations of requested features. It seems to be working, so far).
There is a pydoctor component in the trac instance on twistedmatrix.com. Assign to mwh.
Also, if it's daytime in Europe, turning up in #twisted and hassling mwh works reasonably well.