There are two main ways to customize your documentation beyond what is possible with core Sphinx: extensions and themes.
In addition to these configuration values, you can customize Sphinx even more by using :doc:`extensions </usage/extensions/index>`. Sphinx ships several :ref:`builtin ones <builtin-extensions>`, and there are many more :ref:`maintained by the community <third-party-extensions>`.
For example, to enable the :mod:`sphinx.ext.duration` extension,
locate the extensions list in your conf.py and add one element as
follows:
# 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/indexThemes, on the other hand, are a way to customize the appearance of your documentation. Sphinx has several :ref:`builtin themes <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 furoAnd 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 :doc:`expand the narrative documentation and split it into several documents </tutorial/narrative-documentation>`.
