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:
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
ywill create two separate folders (
source/) for our docs. I think this is the best choice if we want to keep everything in order;
Project version: I highly suggest to take a look at Semantic Versioning to choose the most suitable version at this stage;
Create Makefile?: choosing
ywill 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
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 ├── 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:
NOTE: if you do not want to change directory, you can also use
make -C docs/ html, where
-Cspecifies 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):
--force: overwrite all files generated by Sphinx;
-M: put module documentation before submodule documentation.
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:
Your module description
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
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
pip install sphinx_rtd_theme
then add the following lines to your
# 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
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.
Why installing Sphinx inside virtualenv?
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.