The Navigatrix has been updated. The new website can be found at navigatrix.net.




Post new topic Reply to topic  [ 5 posts ] 
Author Message
 Post subject: Navigatrix Documentation Re-loaded
Site Admin

Joined: 20 Mar 2012, 13:32
Posts: 116
The Navigatrix Documentation has been revamped and is now available in a new and shiny web format.
Attachment:
nxdoc_scrot.jpg
nxdoc_scrot.jpg [ 56.33 KiB | Viewed 20640 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.


Top
   
 
 Post subject: Re: Navigatrix Documentation Re-loaded
Site Admin

Joined: 20 Mar 2012, 13:32
Posts: 116
Thanks to Sphinx the Navigatrix documentationis now also available as an ebook download (EPUB, ~5MB).
Attachment:
nxcover.jpg
nxcover.jpg [ 7.13 KiB | Viewed 20639 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.


Top
   
 
 Post subject: Re: Navigatrix Documentation Re-loaded

Joined: 04 Nov 2010, 20:51
Posts: 1062
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--> http://en.wikibooks.org/wiki/LaTeX/Internationalization will go on the back burner as an investigation for translating the text into other languages.


Attachments:
Navigatrix_Documentation.2014.02.alpha.pdf [312.02 KiB]
Downloaded 627 times
Top
   
 
 Post subject: Re: Navigatrix Documentation Re-loaded
Site Admin

Joined: 20 Mar 2012, 13:32
Posts: 116
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.
Attachment:
Navigatrix.pdf [2.72 MiB]
Downloaded 689 times


Top
   
 
 Post subject: Re: Navigatrix Documentation Re-loaded
Site Admin

Joined: 05 Nov 2010, 01:00
Posts: 185
Thats great ! I realy like this new design... And the new export possibilities. Thats what i always wanted to have!
Thankyou very much :)


Top
   
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 5 posts ] 


Search for:
cron

Credits © 2010 - 2024