Using Sphinx

Getting Started

The official guide to Sphinx can be found here. This is another helpful guide.

If you have cloned the OpenCMP repository, you should have all the necessary Sphinx configuration files already set up. Try the following steps:

  1. Install Sphinx with apt-get install python3-sphinx. Make sure you install for Python 3.6+.

  2. Check if you have “docs/_static” and “docs/_templates/” directories. If you don’t, create empty directories with these names.

  3. Within the “docs” directory in the main OpenCMP directory run make html.

  4. Move to the “docs/_build/html” directory and open any of the .html files (“index.html” is a good one to start with).

If any of the above steps don’t work, run sphinx-quickstart as detailed in the official guide then modify the “conf.py” file as described in the next section.

Configuring “conf.py”

The following lines must be uncommented or added to the top of the file.

import os
import sys
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../'))

Add sphinx.ext.napoleon to the end of extensions so Sphinx can parse Google-style docstrings. The following lines also need to be added directly below extensions.

napoleon_google_docstring = True
napoleon_include_private_with_doc = True
napoleon_use_param = True
napoleon_use_rtype = True

To make Sphinx play nicely with typing add sphinx_autodoc_typehints to extensions. This must be included after sphinx.ext.napoleon or it won’t work.

Set the Sphinx theme to the ReadTheDocs theme with html_theme = 'sphinx_rtd_theme'. The theme can be installed with pip3 install sphinx_rdt_theme.

Some OpenCMP documentation uses Markdown, which must be parsed into reStructuredText using recommonmark before it can be read by Sphinx. Install recommonmark with pip3 install --upgrade recommonmark then add recommonmark to extensions. Finally, add .md to the source_suffix list/dictionary.

ASCII art is made with aafigure. Install aafigure with pip3 install aafigure then add aafigure.sphinxext to extensions.

Helpful Tips

  • If using Markdown, the file titles must be denoted by underlining with “=”. Sphinx doesn’t recognize “#” and will give an error about a missing title.

  • If Sphinx is displaying old docstrings or failing to find modules that have been renamed or removed, delete the “source” directory and then run sphinx-apidoc -o source/ ../ from within the “docs” directory. This will recreate the automatic docstring documentation from the current code base.

  • Running make clean clears anything cached in the “_build” directory.