Use Sphinx for documentation

Published on April 25, 2008 in Python and utilities. 15 CommentsTags: documentation, sphinx, tutorial.

Update: After some folks requested it in the comments, I wrote another post, A minimal Sphinx setup for autodocumenting Python modules. You might want to check this out if you’re specifically interested in automatically documenting your code with Sphinx.

I’ve been doing quite a bit of code documentation lately, and I decided to try and figure out the best tool to use. I found it. It’s called Sphinx, and you can see what the documentation looks like by checking out the documentation for Python itself (v. 2.6and 3.0).
Here’s how to get started using Sphinx.
Sphinx is the name of the program that takes your plain text files and converts them into hyperlinked, nicely formatted HTML documents. It knows what to link and how to format based on simple formatting commands in the text files (specifically, it uses theReStructured Text (ReST) markup language).

Installation

It is really, really easy.

If you have easy_install on your machine, running

easy_install sphinx -U

from the command line will do it.

If you don’t have easy_install yet, download and install it, then run easy_install sphinxfrom the command line.

Run sphinx-quickstart to automatically setup a directory structure

Navigate to the directory that you want to generate documentation for. Run sphinx-quickstart from the command line. You will get a series of questions that lead you through the process of setting up the directories and some files that Sphinx needs. Most questions have defaults that you can just accept no prob. When it comes to version name, you can just make something up.

If you accepted all the defaults (you conformist, you!) there are now a couple of new files and directories:

New directory contents:

/.build

/.templates

/.static

index.rst

conf.py

In a moment we’ll look at index.rst and conf.py. But first . . .

Create some content

Time to make some content. All content is created in plain text files. Create a new text file in the same directory as index.rst and conf.py. Call it chapter1.rst or something . . . what’s important though is that you give it the “.rst” extension (if you chose the default option for “Source file suffix” when you ran sphinx-build, otherwise the extension must be whatever you chose in that step). Sphinx will recognize files that should be included based on their extension. Since I tend to have random, non-documentation .txt files laying around which Sphinx will ask me about, I prefer to use .rst instead of .txt.

Inside chapter1.rst, type some stuff. You could be documenting the code that’s in the current directory, for example. Here are some formatting elements you can try for now. The Sphinx site has lots more info on formatting.

This is a header

================

Some text, *italic text*, **bold text**

* bulleted list.  There needs to be a space right after the "*"

* item 2

.. note::

This is a note.

Here's some Python code:

>>> for i in range(10):

...     print i

Once Sphinx is set up, it will read in the plain text above and convert it into some nicely formatted HTML. The results of the above plain text will look something like this:

But first you have to run it through Sphinx in order for it to look that way, and before you can do that you have to tell Sphinx to include this document in its processing.

Tell index.rst what files to include

Now we have to edit index.rst to tell Sphinx that chapter1.rst should be included in the documentation. By default, index.rst looks like this:

Change this . . .

Welcome to my project's documentation!

======================================

Contents:

.. toctree::

:maxdepth: 2

Indices and tables

==================

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`

To this . . .

(Just add the chapter1.rst line)

Welcome to my project's documentation!

======================================

Contents:

.. toctree::

:maxdepth: 2

chapter1.rst

Indices and tables

==================

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`

The indentation of the chapter1.rst line is important. So is the blank line above, and the blank line below.

BE CAREFUL . . . this burned me the first time, and took a while to figure out. See the :maxdepth: 2 line? It’s only indented 3 spaces. It doesn’t have to be 3 spaces, it just happens to be in this auto-generated file. If you have your text editor set for 4 spaces, or anything other than 3 spaces, when you hit tab on another line your indentation will be inconsistent, resulting in errors.

Usually I just add a space to make the :maxdepth: 2 line a 4-space indentation.

Build the documentation

Back at the command line, make a new directory to hold your documentation. I’m going to call mine doc.

mkdir doc

Then, in the same directory as index.rst, run

sphinx-build . doc

You’ll get some output that tells you what it’s doing.

View the result

Now you can open up doc/index.html to view your newly generated documentation. It looks something like this:

Clicking on the “This is a header” link shows you the content you added in chapter1.rst, and it looks something like this:

So what’s the big deal?

The above example could have been done with a little work in Microsoft Word. Where Sphinx really shines, though, is when you use it to document Python code.

Sphinx can auto-document by reading in a module, then displaying the docstrings of objects in that source code. It hyperlinks modules, classes, methods, attributes, etc. It can even take the code you write as a tutorial and use it as doctests, which test your code to ensure that it is correct. With a little more setup, you can generate LaTeX (and then PDF files) of your code, along with the good-looking syntax highlighting. (see upcoming posts for how to do all of this)

I feel that other documentation tools, like epydoc, have too much of an auto-generated look, and it’s too easy to include extraneous content. In order to include tutorial info in epydoc documents, you have to add text to the beginning of a module. While epydoc has some nice formatting (allowing you to tag text as parameters or return values), it tends to look ugly–sometimes to the point of unreadability.

I like Sphinx because it allows you to insert auto-generated documentation when you need it but tends to focus on high-quality, handwritten, tutorial-style content which I think is the most effective kind of documentation.