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:
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.