The Navigatrix Documentation has been revamped and is now available in a
new and shiny web format.
Attachment:
nxdoc_scrot.jpg [ 56.33 KiB | Viewed 16656 times ]
With the exception of the 'index' file I've left the old documentation's HTML files on the server. That way, hardlinks to individual pages from the discussion board should still work.
Why the revamp? Maintaining the documentation's source in HTML has become a bit of pain - to the point where it actually deters me from making updates/additions - let alone some else... Recently I've come across reStructuredText and Sphinx. The former is a minimalistic text markup convention ('reST' for short, similar to 'markdown' plus a few extras) and the latter a very powerful tool to automagically turn a set of reST documents into almost any useful output format, including websites and ebooks.
reST files look almost like plain text files because the markup is very non-intrusive. For example, a heading is denoted simply by underlining the text and as long as you are consistent with your underlining symbols for different heading levels, Sphinx will automatically infer the correct hierachical structure. Since reST was specifically designed for software documentation (Python) it also has excellent support for quoting code, commands, and the like. Consequently, maintaining the documents in reST rather than HTML makes it *a lot* easier to make updates, since it feels like editing a plain text file rather than a thick under brush of HTML tags.
Sphinx is a piece of software that was developed to turn software documentation from a set of reST files into nicely packaged outputs. The program is brilliant. After running it's 'quickstart' module in your project directory you simply tell it 'make html' or 'make ebub' and out comes stuff that looks like the new Navigatrix documentation (or the official Python documentation for which Sphinx was originally built).
Anyway, so far it's just a new and shiny front... now we'll actually have to add some new content...
PS: For the initial step of the revamp - turning HTML into reST - pandoc has been great - a real Swiss army knife for single document format conversions. It's in the repositories if you ever need one.
