Farm Development

Housecall from the pydoctor (finally, a doc generator that works!)

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.

  • Re: Housecall from the pydoctor (finally, a doc generator that works!)

    I tried to try it. Installed Nevow from SVN but pydoctor gets an ImportError on this line:

    from nevow import loaders, tags, page, flat, inevow

    I'll trac the pydoctor guys.

  • Re: Housecall from the pydoctor (finally, a doc generator that works!)

    Looks like I had revision 11401 of Nevow. In the meantime, you can perhaps install that one until the error is resolved.

Note: HTML tags will be stripped. Hit enter twice for a new paragraph.

Recent Projects

  • JSTestNet

    Like botnet but for JS tests in CI.

  • Nose Nicedots

    Nose plugin that prints nicer dots.

  • Fudge

    Mock objects for testing.

  • Fixture

    Loading and referencing test data.

  • NoseJS

    Nose plugin that runs JavaScript tests for a Python project.

  • Wikir

    converts reST to various Wiki formats.