Sphinx Development Environment

We use a Python library called Sphinx to generate documentation from ReST files.

Installing Python

If you haven’t already installed Python 3, see Installing Python. When you come to the end of the Python installation section, come back to this guide.

Installing Sphinx

Installing Sphinx on Linux

In Ubuntu, Sphinx is very easy to install, as it works with Python 3.

To install on Ubuntu, simply run…

sudo apt install python3-sphinx pandoc

Installing Sphinx on Mac

We can install Sphinx on Mac using either Homebrew or MacPorts.

Installing Via MacPorts

sudo port install py36-sphinx pandoc
sudo port select --set sphinx py36-sphinx

SOURCE: Installing Sphinx - MacPorts

Installing Via Homebrew

brew install sphinx-doc pandoc

SOURCE: Installing Sphinx - Homebrew

Installing Sphinx on Windows

You can install Sphinx using Python pip.

python -m pip install -U sphinx

Then, download and install Pandoc from its official website: http://www.pandoc.org/installing.html.

SOURCE: Installing Sphinx - Windows

Choosing an Editor

ReST files are just plain text files written in the ReStructuredText markup language. Thus, you can edit them in any text editor.

However, we’ve found that Visual Studio Code handles ReST files uncommonly well. You can also use a plain text and code editor, such as Geany.

If you’re using VSCode, make sure you install the Esbonio extension by Swyddfa.

Writing and Editing Documentation

To get started editing documentation, create or open a file in the docs/source directory of the repository for whatever project you’re documenting. (Some projects may put documentation in a different outer directory than docs/.

Index

source/index.rst is the main file in your documentation. To add a file to the automatic table of contents tree, list it below this section:

.. toctree::
   :maxdepth: 2

You only need to list the name of the file, without the extension. If it is within a subfolder in source/, just write out the relative path.

For example, if you had the file foo.rst in source/ and baz.rst in source/bar/, you can add them like this:

.. toctree::
   :maxdepth: 2

   foo
   bar/baz

Important

Note that I lined everything up, so both of my new entries have the same number of leading spaces as :maxdepth: 2. ReST is VERY finicky! You should line things up exactly.

Adding a New File

To add a new file to your documentation, create a file in the docs/source directory (or a subdirectory thereof) with the .rst extension.

A good filename should be all lowercase, with underscores where necessary. For example, goldilocks.rst would be a good file name for the Goldilocks documentation.

Documentation pages can be quite long, and that’s fine. Sphinx subdivides large documents beautifully, so you can generally devote one single document to one single module, section, or topic.

Once you click Save, your editor will probably know to treat the file as a ReST document.

Rendering Final Output

It is super simple to render the gorgeous output of your documentation with Sphinx. In your Terminal, go to your docs/ folder, and simply type…

make

…to list out all the supported formats. My favorite is HTML, which generates a snazzy, searchable web version. To output to HTML, type…

make html

Double-check the Terminal output. If it complains about any errors or warnings, be sure to fix them! Errors are pretty obvious in Sphinx - missing documents, malformed tables, and so on.

Hint

Because Sphinx is the standard way of creating documentation for Python projects, the #python IRC channel is a really good place to get help.

Once the HTML is created, go to build/html/, and open index.html in your favorite web browser.

Setting Up Documentation

Warning

If your project already has documentation, skip this section!

In the repository for the project that you want to create the documentation for, run…

mkdir docs
cd docs

This creates a new folder docs for our documentation, and navigates into it. Then, run…

sphinx-quickstart
  • Below are the settings you should select during Quickstart. I’ve marked ENTER for those options that you should use the default on.

  • Root path: ENTER

  • Separate source and build: y

  • Name prefix for templates and static dir: .

  • Project name: <name of your project>

  • Author name(s): MousePaw Media

  • Project version: <short project version>

  • Project release: <long project version>

  • Project language: Enter

  • Source file suffix: Enter

  • Name of your master document: Enter

  • Do you want to use the epub builder?: y

  • Use defaults for the rest of the options.

Note

You can change most of those options again later.

Before continuing, you should also edit your .gitignore file, adding the line:

build/

This ensures that Sphinx’s output is not tracked by the repository.

Configuring

source/conf.py is the configuration file for Sphinx. This is where you change things like project name, author, copyright, and version, as well as build options and theme.

If you just created this documentation directory, open this file and then look for html_theme. Change this from alabaster to sphinx_rtd_theme. The new line should look like this:

html_theme = 'sphinx_rtd_theme'

Learning ReStructuredText

ReStructuredText is a markup language all its own. It has a ton and a half of awesome features, but it’s hard to know them all. Check out Sphinx’s documentation for help with all things Sphinx and ResT! I’ve linked you above to the best page to start with.