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?