Home » Documentation guide » Tools for documentation writing »

Introduction to Sphinx

Philosophy

Sphinx is what is called a documentation generator. This means that it takes a bunch of source files in plain text, and generates a bunch of other awesome things, mainly HTML. For our use case you can think of it as a program that takes in plain text files in reStructuredText format, and outputs HTML.

reST -> Sphinx -> HTML

So as a user of Sphinx, your main job will be writing these text files. This means that you should be minimally familiar with reStructuredText as a language. It’s similar to Markdown in a lot of ways. It’s a lot more powerful than Markdown, but with that power comes increased complexity. Just know that some of the awkward syntax allows you to do more interesting things further down the line. In particular, it is extensible: it has a formal way of adding markup directives that allow more sophisticated parsing. For example, Sphinx includes directives to relate documentation of modules, classes and methods to the corresponding code.

Installing Sphinx

The first step to getting going is installing Sphinx. Sphinx is a Python project, so it can be installed like any other Python library. Several Operating Systems (Mac OS X, Major Versions of Linux/BSD) have Python pre-installed, so you should just have to run:

sudo pip install Sphinx

Instructions for installing Python and Sphinx on Windows can be found at the Sphinx install page.

Note

Advanced users can install this in a virtualenv if they wish.

Getting started

You’ll want to read the Sphinx Getting Started guide, as it provides an introduction to a lot of the basic ideas. If you use the sphinx-quickstart tool described there, it’ll create a sample project with the following standard structure:

project/
    docs/
        conf.py
        index.rst
        Makefile

We have a top-level docs directory in the main project directory. Inside of this is:

index.rst:
This is the index file for the documentation, or what lives at /. It can be thought of as a landing page that contains child topics for users to navigate to. It normally contains a table of contents that will link other topics in the documentation.
conf.py: which allows for customization of the output.
For the most part this shouldn’t need to be changed.
Makefile: This ships with sphinx,
and is the main interface for local development, but shouldn’t be changed.

Other *.rst files for specific subsections of documentation.

Table of contents structure

The method for specifying a table of contents (TOC) structure in Sphinx is somewhat unusual. Instead of a master file that contains the hierarchical structure of the TOC for the whole project, you’ll need to include toctree directives in each parent topic that has child topics. Sphinx will then infer the overall TOC structure from the toctree directives in individual files.

For example, the index.rst file in your project folder may contain the following toctree directive:

.. toctree::

   TopLevel1
   TopLevel2

This indicates that there are two top-level topics. If you want the TopLevel1 topic to contain child topics, then you’d insert the following toctree directive in TopLevel1:

.. toctree::

   Child1
   Child2
   Child3

Different Sphinx themes will have different ways of displaying the TOC in the sidebar. You can also configure whether or not to display the toctree directive as a mini-toc within the topic itself, by adding a :hidden: option to the toctree directive.

Writing docs

Where you write your documentation will vary based on how the project is laid out. Generally major topics will go in an aptly named file in the top-level docs directory. If a topic gets larger, it can then be broken out into multiple files in a directory. When you write a document, figure out if there is already a place for it in the project, otherwise feel free to start a new file.

Warning

If you make a new file, make sure it is included in a toctree directive in a file that is in the TOC. When you build the documentation, Sphinx will display a warning for each document that isn’t in the TOC.

reStructuredText

To write nice looking documentation you will need to have a basic understanding of RST as a language. The reStructuredText Primer is a great place to start reading, and it covers most of the syntax you will care about. The main parts you will need at first are:

  • Inline Markup
  • Source Code
  • Hyperlinks
  • Sections
  • Directives

Note

You can live-preview RST on the web: http://rst.ninjs.org/ . Note that it won’t understand Sphinx-specific markup though.

Feel free to play around with RST a bit to make sure that you understand how it works.

Warning

RST is white-space sensitive in places. If it is acting weirdly, make sure you indent lines that are part of the same content similarly.

Building docs

Once you have your documentation written and want to turn it into HTML, it’s pretty simple. Simply run:

# Inside top-level docs/ directory.
make html

This should run Sphinx in your shell, and output HTML. At the end, it should say something about the documents being ready in _build/html. You can now open them in your browser by typing:

open _build/html/index.html