Documentation and Auto-documentation (My day in tracking things down...)


Spent the first 8 or so hours of the day tracking down documentation, creating auto-generated documentation and the like. Results are on the Tutorials and API Reference pages on the wiki.

Then sat down to work on making a simple API documentation system that's template based. Working off epydoc's introspection mechanism for that. So far it seems pretty straightforward. I'm basically using the plain-text formatter from epydoc as a guide to how to use the APIDoc objects and am coding up Kid template fragments for each item.

Things I want from the generator:

* allow for special handling of exotic types (e.g. D-BUS services)
* allow for non-trivial customisation of the display format just by editing XHTML templates
* minimum of "machinery" around the documentation and a minimal size where possible
* allow for "foreign reference" definitions so that we can link to e.g. the standard Python docs and standard GTK docs rather than building them ourselves
* allow for "foreign include" definitions so that we can define documentation fragments, (both method-description and docstring) outside the source-code
* allow "usage example" definitions so that from any given class/function/method the user can jump to code that uses the class/function/method

anyway, for right now it's nowhere near there, I'm still working on the basic "show what's in the module" functionality, so for now we have the super-ugly pydoc2 version.

Comments

Comments are closed.

Pingbacks

Pingbacks are closed.