Seems like I need to have a look at a reasonable documentation system that will let me generate man pages, info files, HTML and pdf docs all from one source.
I recommend Twisted's Lore package, which will be part of the imminent 1.0.1. Lore can output HTML and LaTeX (and thus ps and pdf) from XHTML source. Actually, it's a subset of XHTML, and it uses the class attribute alot to provide semantic rather than presentational markup, e.g:
... will return a <code class="API" base="twisted.internet.defer">Deferred</code>.
or:
You can footnote<span class="footnote">This is a footnote.</span> text.
It's currently geared towards Python docs, i.e. it can pretty-print python code and automatically link API references to epydoc's output, but is easily extensible. Docbook output is in the works (which in turn provides for info pages), and we have a man2lore utility, which is simple but sufficient for Twisted's manpages.
It does nice things like turn relative links to other HTML files into LaTeX cross-references, and so forth. It automatically creates a table of contents for the HTML output based on your H1, H2, etc tags. And a nice side-effect of using XHTML as source means that the unprocessed source document is directly viewable (although occasionally ugly, such as with footnotes (but stylesheets can help)), which is handy.
It's also quite small; there's only about 600 lines of source that does all this, and it includes a lint utility! So, it shouldn't be too scary to work with, even if you don't know Python. Feel free to ask about it on #twisted (on freenode) or the mailing list if you're interested, we'd be happy to help.
Hacking:
I was going to talk about the fun I've been having working on Lore, but I think I've probably covered that quite well already for this entry :)
Last modified: 22 November 2002
Powered by backwards