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
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¶
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
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.