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¶
For example, to enable the
extensions list in your
conf.py and add one element as
# 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¶
For example, to use the Furo third-party theme
in your HTML documentation, first you will need to install it with
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:
# 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:
It is now time to expand the narrative documentation and split it into several documents.