index - usage - launchpad

pydoctor

What is pydoctor?

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

Why?

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.

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 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.

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 Bazaar:

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

This is a big enough topic to deserve its own page.

What does the output look like?

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

The output is reasonably simple, clean HTML (it validates!) created from Twisted 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 Launchpad.

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