Writing Documentation with Restructured Text and Sphinx

Nov 14, 2013 · by Suzanne Dergacheva

Documentation is great, and clear, consistent, easy-to-read documentation is even better. Sphinx is a tool that helps you create structured documentation that looks great. Using Sphinx, you can write your documentation using the restructured text markup language. Sphinx then uses the Python docutils library to parse the restructured text files into other formats (HTML, PDFs, etc).

There are lots of advantages to using this method for writing documentation. You can use themes to change the styling of the documentation, and you can control how the documentation is formatted, without relying on GUI editors. I find this saves a lot of time, because you don't think about the rendering of the documentation while you're writing it, you just focus on the words, images, and code snippets.

Using restructured text facilitates collaboration, because you can put your files in version control and have more than one person updating the project at a time. It also makes it easy to add code samples inline or directly from a separate code base.

Setting up a New Sphinx Project

Setting up a new Sphinx project is as easy as:

  1. Install Sphinx (just run apt-get install python-sphinx).
  2. Open up a terminal and create a new directory for your project
  3. Inside the new directory, run sphinx-quickstart
  4. This will prompt you for information about your project, you can leave most of the settings as default.
  5. Then, Sphinx will create all the files you need to generate HTML from your restructured text files.

This will create a set of files, include the Makefile, with the settings for your project, and the index.rst file, which is the master file for your documentation. The index.rst file includes a table of contents that can link to sub-sections of your document.

Writing the Documentation

You can find some starter documentation for writing restructured text on the Sphinx website. Restructured text is really similar to Markdown, so if you're familiar with that, you'll have no problem picking it up really quickly.

Generating HTML

After you've set up your project, you can run make html in the command line to generate HTML for your project. The generated files will be located in the _build/html/index.html. Just open then up in your browser to review your work. If you don't like the look of the HTML document, you can easily change the theme in the conf.py document. You can find a list of theme options on the Sphinx website. I like the look of the sphinxdoc theme better than default.

Generating PDF from your Documentation

Of course, you also might want to create a PDF from your rst files. This will require using additional packages that do the conversion from restructured text to LaTeX PDF format. You might want to consider installing and running these packages in a separate VM. I've added instructions on GitHub which will guide you through setting up such a VM with Vagrant. When you ssh into your VM, you can just run make latexpdf to make the PDF.

One of the first things you'll probably notice about the PDFs is that there are some blank pages added between chapters and after the table of contents. You can add a setting in your conf.py file to fix this:

latex_elements = {
  'classoptions': ',oneside',
  'babel': '\\usepackage[english]{babel}'

The conf.py file is added to the root of your project and includes settings that control the output of your text files for different formats (HTML, LaTeX PDF, etc). There are lots of other settings that you can change here to customize your PDFs and HTML files.

Sphinx is our current tool-of-choice for creating training materials and documentation for clients, but it has lots of other use cases. You can use it to write books, generate online documentation, or write proposals and other formal business documents.