More Sphinx customization¶

There are two main ways to customize your documentation beyond what is possible with core Sphinx: extensions and themes.

Enabling a built-in extension¶

In addition to these configuration values, you can customize Sphinx even more by using extensions. Sphinx ships several builtin ones, and there are many more maintained by the community.

For example, to enable the sphinx.ext.duration extension, locate the extensions list in your conf.py and add one element as follows:

docs/source/conf.py¶

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.duration',
]

After that, every time you generate your documentation, you will see a short durations report at the end of the console output, like this one:

(.venv) $ make html
...
The HTML pages are in build/html.

====================== slowest reading durations =======================
0.042 temp/source/index

Using a third-party HTML theme¶

Themes, on the other hand, are a way to customize the appearance of your documentation. Sphinx has several builtin themes, and there are also third-party ones.

For example, to use the Furo third-party theme in your HTML documentation, first you will need to install it with pip in your Python virtual environment, like this:

(.venv) $ pip install furo

And then, locate the html_theme variable on your conf.py and replace its value as follows:

docs/source/conf.py¶

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'

With this change, you will notice that your HTML documentation has now a new appearance:

HTML documentation of Lumache with the Furo theme¶

It is now time to expand the narrative documentation and split it into several documents.