Introduction to Sphinx¶
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.
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.
Advanced users can install this in a virtualenv if they wish.
You’ll want to read the Sphinx Tutorial, as it provides an introduction to a lot of the basic ideas. For the most part documentation follows a standard structure for our documentation repository:
project/ docs/ conf.py index.rst Makefile
We have a top-level
docs directory in the main project directory.
Inside of this is:
- This is the index file for the documentation, or what lives at
/. It normally contains a Table of Contents that will link to all other pages of 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.
*.rst files for specific subsections of documentation.
Where you write your documentation will vary based on how the project is layed 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.
If you make a new file, make sure it is included in the Table
of Contents in
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
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.
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.
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
You can now open them in your browser by typing: