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.
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 (
==== 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 (
test.html) will now be in the
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
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:
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
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.
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.