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.

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:

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

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 wont be long until you realize that something is missing!

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):

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.

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 namesadd_module_names = False

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

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 themeimport sphinx_rtd_themehtml_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.

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.

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.