Templated PyDoc-ish Tool?

So I'm once again trying to fix the PyOpenGL/OpenGLContext pydoc stuff.  They've been using a hacked up version of pydoc for years (with a brief excursion into epydoc with extensions) and somewhere along the way the changes to the structure of the libraries means that the output is now basically useless.  The key here is that there are a *lot* of function-like objects that are not actually functions, and which need special handling, e.g. to automatically describe the wrapping process, deprecations, argument types, constants, field descriptors, etceteras.

What I'd like to see is a simple (preferably Genshi) template-based PyDoc equivalent, something designed to be used with large projects where you want to write custom documentation templates for particular types of objects but can call/use the standard templates/tools for the rest of the code.  Something that lets you do normal template-type styling (headers, footers, etceteras), use CSS for all display considerations, and generally looking good.

The idea being that library would define template functions for every operation (with a reasonable degree of granularity), provide a reasonable default template, and let you customize the behaviour as you need for your project.

This is now at least my 5th post about this, 2005, 2006 and twice in 2007... is it just that I'm out of the loop for auto-documentation tools? Is someone hiding the holy grail of auto-doc right beneath my feet?


  1. Richard Jones

    Richard Jones on 12/15/2009 4:13 a.m. #

    I've not used it but isn't Sphinx the bee's knees these days?

  2. Tony

    Tony on 12/15/2009 4:51 a.m. #

    +1 for Sphinx. With the automodule and autoclass directives, you get a lot of documentation 'for free' - free that is, if you've written docstrings.

    You can also do some magic with doctests as well, but I've not gone that far.

    It actually makes you *want* to write docstrings, because they look so good...

  3. Brandon Craig Rhodes

    Brandon Craig Rhodes on 12/15/2009 8:39 a.m. #

    +1 Sphinx. The templating is very flexible; I just rewrote the pyatl.org web site using Sphinx, and my whole PyEphem web site has been done using Sphinx for a long time, so it will certainly theme for you like you want. You'll just have to try out the autodoc module to see if it grabs all of the docstrings that you want copied over!

  4. Mike C. Fletcher

    Mike C. Fletcher on 12/15/2009 11:34 a.m. #

    I'm familiar with Sphinx from working on the TG2 docs, though to be quite frank I haven't been all that impressed and so had dismissed it from the running. I'll have to look into it again and see what the customization potential is (I'm not just looking to grab docstrings, I want to be able to define new ways of documenting a particular type, potentially with sub-structures and references and all the like).

  5. Eric Larson

    Eric Larson on 12/15/2009 5:45 p.m. #

    While I can't really say how customized you can get with Sphinx, I can say that at my job we've had a tech writer writing docs for using it. I mention it b/c if you are really looking for something that is good for writing docs (as opposed to just pulling in doc strings), my guess is that it is pretty decent. Personally, I've never used it though.

Comments are closed.


Pingbacks are closed.