As an engineering organization grows, eventually there is a need to document more than just code comments. When this happens, there are many solutions for handling documentation, and most of them are equally bad. Previously, at Votizen.com we used a wiki, but it was difficult to organize, search, and links/documents rot. Recently, we chose to ditch the wiki, converting our documents to reStructuredText (.rst), and instead use the tool Sphinx to compile our documents (policies, guidelines, ops, etc.).

Sphinx is a powerful, but simple to setup tool that can compile reStructuredText documents. It improves searching and complains when links break, both of which were big problems we had with the wiki. For version control, we checkin our documents to a Git repository, and have hooks that will complain if broken documents are checked in. We still have the problem of stale documents, but this is a universal problem with documentation.

How do it…

Install Sphinx python package:

pip install Sphinx

Create the document directory and use the Sphinx quick-start to begin documentation:

mkdir docs
cd docs
sphinx-quickstart

There will be a lot of questions, but the defaults can be used for almost all of them. This will create two directories and a MakeFile:

    ./MakeFile
    ./build
    ./source/_static
    ./source/_templates
    ./source/conf.py
    ./source/index.rst

Create a test document (source/test.rst):

====
TEST
====

Some text

Header 1
========

Some more text

Header 2
========

Additional test

* bullet 1
* bullet 2

**bold** *italics*

Subheader
---------

Test

By default, the index.rst will look like:

.. Test Project documentation master file, created by
        sphinx-quickstart on Thu Jul 12 10:22:51 2012.
        You can adapt this file completely to your liking, but it should at least
        contain the root `toctree` directive.

Welcome to Test Project's documentation!
========================================

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

To see some examples of the toctree directive, modify it to look like:

.. Test Project documentation master file, created by
        sphinx-quickstart on Thu Jul 12 10:22:51 2012.
        You can adapt this file completely to your liking, but it should at least
        contain the root `toctree` directive.

Welcome to Test Project's documentation!
========================================

Contents:

.. toctree::
   :maxdepth: 2

   test

Header 1
--------

.. toctree::
   :maxdepth: 1

   test
test # notice this is not a reference

Header 2
--------

.. toctree::
   :maxdepth: 1

   test
   test

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Now compile your documents:

make clean html

The newly created documents (index.html and test.html) will now be in the build/html directory.

How it works…

Documents need to be written in reStructuredText format. Here are the guidelines:

reStructuredText

Sphinx will build an easy to use and search collection of HTML files based on the reStructuredText documents referenced from the index.rst, and chained therefrom. Documents may be organized flatly or in subfolders inside the source directory, but when using subfolders, the whole relative path will need to be used to link documents (ie. subfolder/test instead of test). The conf.py in the source directory contains the rules setup by the quick-start command, and is used by Sphinx to create the documents. For additional information on Sphinx see:

Sphinx - Python Documentation Generator

The changes made to the index.rst help show how to use the toctree directive, which is used to build a table of contents. When defining a toctree the maxdepth will indicate the depth for linking reStructuredText headers. A depth of one will only link to the page, and each depth level further will link to an additional header level. It is important that all linked documents are indented to the same level as the maxdepth directive, or they will be treated as plain text.

There’s more…

This tutorial creates an HTML version of the documents, but if you look at the MakeFile there are many other output options as well.

As always, if you have questions, please leave a comment. But also, don&8217;t hesitate to link great examples of people using Sphinx on the web.