Why Sphinx and reStructuredText ?

How I got into Sphinx

I usually take notes for myself while installing new software, just to ensure that if I have to do it again for any reason, I will be able to avoid the little traps and caveats along the way. And I also hope to make others’ life easier by providing them with those instructions. Indeed, when searching the Internet while facing a given problem, I often realize I’m not the only one in trouble, so why not make others save their precious time?

Initially, I wrote my notes directly on simple text files using a simple notepad, because I found it simpler like this (no need for an advanced interface, I just wanted some trace of my actions). I did that for a while, for several projects. But at a certain point, I realized that I had plenty of text files spread over my computer containing lots of useful notes over complex installation of software, but at the end, even with a good classification system and even for me (who wrote the whole thing!) it became difficult to go through old files. Plus, they were pretty ugly, preventing them to be shared with others.

And here came Sphinx, the Python Documentation Generator! I discovered that system while struggling to install OpenCV from the sources with some custom settings that I wanted for my thesis. As my installation instructions text file became larger and larger, I realized it would by great to have my own instructions look the same as the documentation I was reading. In particular, I was using the Windows installation tutorial on docs.opencv.org and this tutorial looked pretty nice. At some point, a little link “Show Source” showed me the actual source of the web page, which was not ugly at all, even though apparently based on a single text file, similar to the text files I was producing by myself.

So I decided to translate my notes into the Sphink format (actually reStructuredText) and to share it with others for the greatest benefit of all interested people.

The following web pages got me quickly started with Sphinx:

Later, I wanted to know how did Sphinx compare with respect to other documentation systems. I found a nice and concise comparison between Sphinx and the other documentation systems, which is detailed in the next section.

Excellent Sphinx motivations

The first school of thought on documentation, is the one we subscribe to in Varnish right now: “Documentation schmocumentation...” It does not work for anybody.

The second school is the “Write a {La}TeX document” school, where the documentation is seen as a stand alone product, which is produced independently. This works great for PDF output, and sucks royally for HTML and TXT output.

The third school is the “Literate programming” school, which abandons readability of both the program source code and the documentation source, which seems to be one of the best access protections one can put on the source code of either.

The fourth school is the “DoxyGen” school, which lets a program collect a mindless list of hyperlinked variable, procedure, class and filenames, and call that “documentation”.

And the fifth school is anything that uses a fileformat that cannot be put into a version control system, because it is binary and non-diff’able. It doesn’t matter if it is OpenOffice, LyX or Word, a non-diffable doc source is a no go with programmers.

Quite frankly, none of these works very well in practice.

One of the very central issues, is that writing documentation must not become a big and clear context-switch from programming. That precludes special graphical editors, browser-based (wiki!) formats etc.

Yes, if you write documentation for half your workday, that works, but if you write code most of your workday, that does not work. Trust me on this, I have 25 years of experience avoiding using such tools.

I found one project which has thought radically about the problem, and their reasoning is interesting, and quite attractive to me:

  1. TXT files are the lingua franca of computers, even if you are logged with TELNET using IP over Avian Carriers (Which is more widespread in Norway than you would think) you can read documentation in a .TXT format.
  2. TXT is the most restrictive typographical format, so rather than trying to neuter a high-level format into .TXT, it is smarter to make the .TXT the source, and reinterpret it structurally into the more capable formats.

In other words: we are talking about the ReStructuredText of the Python project, as wrapped by the Sphinx project.

Unless there is something I have totally failed to spot, that is going to be the new documentation platform in Varnish.

[...]

Written by Poul-Henning (2010-04-11) in the Varnish-cache documentation.

Quick description of my Sphinx installation

I personally use Sphinx on Windows, with MinGW and Powershell. I created a make alias for mingw32-make and used the sphinx-quickstart command to get started. I modified the default HTML theme into the nature one by modifying the appropriate line in the conf.py project configuration file. I also recommend using Sublime Text to edit the source files as it natively supports reStructuredText highlighting.

I generate both HTML and PDF doc to publish in my personal website and to share with friends and colleagues, respectively.