How to generate documentation with Sphinx

fievelk · April 7, 2017

How To   Python

Sphinx is a documentation generator that can help building great docs for our projects in a very short time. In this tutorial I will show how to use it to build docs starting from pre-existing Python docstrings.

Installing and configuring Sphinx

NOTE: If you are developing your Python package using virtualenv, I recommend installing Sphinx directly inside your virtual environment (see explanation at the end of the article).

In order to start working with Sphinx, we need to install it first. Unsurprisingly, this is as easy as:

pip install sphinx

We can now proceed and generate all the files that will be used by Sphinx to build our documentation. From terminal:

sphinx-quickstart

At this point the script will ask us to specify more details about our configuration. Here are some of the basic customizations we will be asked about:

  • Root path for the documentation: I usually choose docs/, to keep documentation separate from the rest of the project;
  • Separate source and build directories: choosing y will create two separate folders (build/ and source/) for our docs. I think this is the best choice if we want to keep everything in order;
  • Project name;
  • Author name(s);
  • Project version: I highly suggest to take a look at Semantic Versioning to choose the most suitable version at this stage;
  • Create Makefile?: choosing y will make things a bit easier later.

Sphinx ships with some extremely useful extensions that will make your life much easier. It is therefore important to choose the right ones for your needs. I usually use autodoc, todo, viewcode and githubpages. Note that these preferences can also be added to the conf.py file later.

In order to be quicker, we could also specify all of the above preferences in one command as follows:

sphinx-quickstart --sep -p 'Project Name' -a 'Author Name' -v '0.1.0' --makefile --ext-autodoc --ext-todo --ext-viewcode --ext-githubpages docs/

You should now see a structure like the following for your docs folder:

docs
├── Makefile
├── build
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

Building the docs

We can now proceed and let Sphinx build all the HTML files for our docs.

NOTE: HTML is not the only available format. You can use LaTeX, text, XML, and many others (see sphinx-build buildername options).

In order to do so, we will use the make command that we asked for during the configuration step above. Place yourself within the docs/ folder and issue the following command:

make html

NOTE: if you do not want to change directory, you can also use make -C docs/ html, where -C specifies the directory inside of which you want to issue the command.

At this point your build should have succeeded and your HTML files should be in docs/build/html. You can therefore open index.html in your browser and start taking a look around at your brand new docs. It won’t be long until you realize that something is missing!

Generating documentation from docstrings

What we did so far was to simply generate a sort of scaffolding for our documentation. However, we never explicitly told Sphinx to use our docstrings to automatically populate our docs! This is exactly what the sphinx-apidoc command does. From terminal:

sphinx-apidoc <path-to-project-package> -o docs/source -f -M

The above command uses the following options (you can omit them if you want):

  • -f, --force: overwrite all files generated by Sphinx;
  • -M: put module documentation before submodule documentation.

Customizing conf.py

Several customizations can be done to our docs to make them look shiny. The main place where magic happens is the conf.py file within our documentation folder. I will now share a few tricks that could help improving your documentation.

Hiding full module names

The vanilla configuration will produce an output where classes and methods described by the docs are nested inside their module name. However, all these entities will be prepended with their full namespace. For example:

module.long.full.name module

Your module description

class module.long.full.name.MyClass

As you can see, the full module name (module.long.full.name) is prepended to both the module (above) and the class (below). Since the class belongs to the module, we could reasonably prefer to hide the full module name and just keep the class name (MyClass) instead. In order to do so, we can add the following line to our conf.py configuration file:

# Do not prepend names to object names
add_module_names = False

We subsequently have to re-run the sphinx-apidoc and make commands as above to rebuild the HTML output files.

Changing Sphinx docs theme

Sphinx ships with several builtin themes that we can choose from. Additionally, we can also choose a customized theme (or create our own). In my case, I often go for the Sphinx ReadTheDocs theme. If you want to use it as well, install the sphinx_rtd_theme package:

pip install sphinx_rtd_theme

then add the following lines to your conf.py:

# Use ReadTheDocs theme
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

We can now run again the sphinx-apidoc and make commands as seen above.

More

Many other customizations can be used to improve our documentation. Please make sure to read the Sphinx build configuration file docs if you want to achieve the best results for your project.

Notes

Why installing Sphinx inside virtualenv?

The make command that we use calls sphinx-build, which in turn uses the default Python interpreter. This means that if we install Sphinx inside the virtual environment, sphinx-build will correctly call the Python version in use for our project. Why is it important? The project needs to be installed in order to be found by Sphinx; since we probably installed it using pip install -e, Sphinx will only be able to find it with regards to the Python version used by our current virtualenv.

Sources

Twitter, Facebook