Skip to content

Latest commit

 

History

History
78 lines (56 loc) · 2.47 KB

File metadata and controls

78 lines (56 loc) · 2.47 KB

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 :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/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 :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 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:

HTML documentation of Lumache with the Furo theme

HTML documentation of Lumache with the Furo theme

It is now time to :doc:`expand the narrative documentation and split it into several documents </tutorial/narrative-documentation>`.