Last week, in Write Documentation Once, Output Multiple Formats with Sphinx we learned how to install the Sphinx documentation generator, and how to build HTML, PDF, Epub, and other documents from a new Sphinx installation. Today we’re going to create a small test project with some original content, and mark it up using RST, the native Sphinx markup language. Then you can build multiple output formats from your single source. All you need is your favorite text editor and a working Sphinx installation.

The example project for this article is simple and demonstrates the essentials. Start by downloading the main example page, example.rst, the screenshot of the rendered HTML page, sphinx-html-page.png, and the other project files from Google drive. example.rst is a Sphinx source file, and sphinx-html-page.png shows what it looks like after running the make html command.

Sanity Tips

When you need help always refer to the Sphinx reference manual, rather than wasting time on Web searches full of wrong answers.

Sphinx is written in Python, so whitespace matters. Run frequent builds, as this is the fastest way to find markup errors. This example from running make html finds an error and tells us exactly where it is:

book1$ make html
[...]
/home/carla/book1/content/example.rst:23: WARNING: Title underline too short.
First-level Subhead
=================

Documentation Structure

In the example project for this article, the project file structure looks like this:

book1
|--_build
|-- conf.py
|-- content
   |-- example-2.rst
   |-- example.rst
|-- images
   |-- blue-marble.jpg
   |-- moon-from-space.jpg
|-- index.rst
|-- Makefile
|-- _static
|-- _templates

book1 is the project’s root directory. When you run your build commands, the output goes into the _build directory. All of the files were created by the sphinx-quickstart script (see part 1) except the content and images directories. Those are my example content files, and index.rst was modified to include the content files.

Your source files should have the .rst file extension. (This is configurable in conf.py with the source_suffix parameter.) When you reference your .rst files in internal links and the table of contents use only the filename and omit the extension. For image files you must specify the full filename, including the extension.

Titles and subheadings are marked-up with a variety of punctuation marks. You may use whatever punctuation marks you like, or adornments as the Sphinx manual calls them; the order on your page determines how they render. Your adornments must be the same length as your headings. If they are not you’ll see warnings in your build output.

Your table of contents page is defined in conf.py with the master_doc parameter. For this project the TOC source file is index.rst. The example project is simple, containing only two pages, so the TOC is simple:

.. index.rst
=================
Table of Contents
=================
.. toctree::
    :maxdepth: 2
    
    content/example
    content/example-2

maxdepth controls how many levels of subheadings your TOC displays, so :maxdepth: 2 displays the page title and the second-level headings. You don’t have to call it “Table of Contents”, but can name it whatever you like. Prefacing any line with two dots and a space prevents it from appearing in the final output, so you can use this for comments as well as formatting directives. In the TOC example .. index.rst is a comment and .. toctree:: is a formatting directive.

Remember that all filepaths (in your TOC, cross references, and image links) are relative to your project root.

Building Your Project

In part 1 we learned how to list and run our available build commands. When you re-run a build command, for example make html, remember to always run make clean first. When you run multiple different builds in succession, do not run make clean because this deletes the contents of your build directory. Instead run them in succession so that they will all appear in your _build directory:

$ make latexpdf
$ make man
$ make epub
$ make text
$ ls _build
doctrees  
latex
man
epub  
text

Now you should have your original source files in four different nicely-formatted outputs. What do you do now? Check out the Sphinx documentation for more features and advanced functionality, starting with how to use conf.py for advanced project control.

Public domain photos of Moon and Earth courtesy Earth Science and Remote Sensing Unit, NASA Johnson Space Center