Documentation tools
Zed Shaw and I spent quite a bit of time talking about Documentation tools, since we are both working on books for Prentice Hall and we both want to have an open-source, reusable tool-chain that helps us get tested code into our documentation easily and effectively.
Zed did a bunch of hacking and came up with this:
http://www.zedshaw.com/projects/zapps/idiopidae.html
Which has a very simple syntax for importing code into your plain-text documentation file. It’s a simple parser that we use to parse the document source and the export files, create parse trees, and do a bit of simple processing. One of the main advantages of this for book writers is that you can have the source code imported into your plain text documentation automatically, and repeatedly. That means you can look at the code while you’re writing. The final parsed output will allow you to convert the plain text document into your final output format (HTML, LaTeX, or whatever) and it will use pygments to code formating/colorization, and interlieve the code into the rendered document.
I also learned that the tool being used to do the new Python 2.6/3.0 documentation has been cleaned up and released as a general purpose documentation tool. It’s ReST (ReStructured Text) all the way, which seems to be a small price to pay for such attractive docs, and such a wide feature set. It also relies on imports from specific line numbers — which is a lot more fragile than marking sections for import, but does not require you to be able to include delimiters in your source code files.
I haven’t had a chance to use it yet, but I’m very excited about it as a tool for the TurboGears online Documentation.
Hooray for better doc tools!