sphinx/doc/tutorial/more-sphinx-customization.rst

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:

.. code-block:: python
   :caption: 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:

.. code-block:: console

   (.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 <https://sphinx-themes.org/>`_.

For example, to use the `Furo <https://pradyunsg.me/furo/>`_ third-party theme
in your HTML documentation, first you will need to install it with ``pip`` in
your Python virtual environment, like this:

.. code-block:: console

   (.venv) $ pip install furo

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

.. code-block:: python
   :caption: 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:

.. figure:: /_static/tutorial/lumache-furo.png
   :width: 80%
   :align: center
   :alt: HTML documentation of Lumache with the Furo theme

   HTML documentation of Lumache with the Furo theme