pydoctor

~mwh/pydoctor/
pydoctor What is pydoctor?

It is an API documentation tool for Python, somewhat like , Pudge (now defunct), or .

Why?

pydoctor was written to be used by the project which was using but was becoming increasingly 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.

Why would I use it? How is it different from Epydoc, pudge, etc?

pydoctor is probably best suited to documenting a library with a some degree of internal subclassing. It also has support for , 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 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.

Who wrote it?

Michael "mwhudson" Hudson, PyPy, Launchpad and sometimes Twisted 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.

Where do I get it?

I still haven't made any proper releases yet, so you have to get it from Launchpad using :

bzr get lp:pydoctor pydoctor How do I use it?

This is a big enough topic to deserve its .

What does the output look like?

It looks like this, which is the Twisted API documentation.

I also periodically run pydoctor on and put the output , 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).

Where do I report bugs?

On .

Also, if it's daytime in New Zealand, turning up in #twisted and hassling mwhudson works reasonably well.