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 "sphinx.ext.duration" extension, locate the
"extensions" list in your "conf.py" and add one element as follows:

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:

   (.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 "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:

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:

   [image: HTML documentation of Lumache with the Furo
   theme][image]HTML documentation of Lumache with the Furo theme

It is now time to expand the narrative documentation and split it into
several documents.
