- A Voyager's Companion

Navigatrix Documentation Re-loaded
Page 1 of 1

Author:  Markus [ 21 Feb 2014, 00:51 ]
Post subject:  Navigatrix Documentation Re-loaded

The Navigatrix Documentation has been revamped and is now available in a new and shiny web format.
nxdoc_scrot.jpg [ 56.33 KiB | Viewed 7884 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.

Author:  Markus [ 21 Feb 2014, 00:57 ]
Post subject:  Re: Navigatrix Documentation Re-loaded

Thanks to Sphinx the Navigatrix documentationis now also available as an ebook download (EPUB, ~5MB).
nxcover.jpg [ 7.13 KiB | Viewed 7883 times ]

The ebook version can be added to the Calibre electronic library that is part of Navigatrix. From Calibre you can transfer it to your favorite ebook reader if you prefer to have an offline copy. If you'd like to print a hard copy, Calibre does a decent job of converting the EBUP to PDF. Just make sure you override the default page size with 'letter' (under 'Look and Feel' in Calibre's conversion dialogue). Otherwise you end up with 350 2.5" x 3.5" sized pages...

[EDIT on 26MAR 2013:] Updated eBook/EPUB version now is ~8MB in size. I'm guessing that changing the images from GIF to JPG is the culprit (required for Sphinx PDF conversion via LaTeX). The content changes are minimal. If you're bandwidth constrained and already have the previous 5MB version it's not worth the new download.

Author:  Moe [ 25 Feb 2014, 21:51 ]
Post subject:  Re: Navigatrix Documentation Re-loaded

This is my first attempt at making a pdf with the fancy software (sphinx/LaTeX) and the git repository.

I don't know what happened to the logo on the 'cover' or why there are two 'these pages are intentionally blank'. It is serviceable if not 100%.

I've proved the process isn't foolproof, but it is fool-resistant.

It was also fun. Thanks for setting this up, Markus.

This--> will go on the back burner as an investigation for translating the text into other languages.

Navigatrix_Documentation.2014.02.alpha.pdf [312.02 KiB]
Downloaded 396 times

Author:  Markus [ 26 Mar 2014, 01:58 ]
Post subject:  Re: Navigatrix Documentation Re-loaded

Here's an updated PDF version (now with table of contents and images) that also includes some minor content updates. These are also reflected in the online HTML version and the EPUB version that is linked above.
Navigatrix.pdf [2.72 MiB]
Downloaded 467 times

Author:  David [ 26 Mar 2014, 12:07 ]
Post subject:  Re: Navigatrix Documentation Re-loaded

Thats great ! I realy like this new design... And the new export possibilities. Thats what i always wanted to have!
Thankyou very much :)

Page 1 of 1 All times are UTC - 5 hours
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group