1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
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
It is now time to :doc:`expand the narrative documentation and split it into
several documents </tutorial/narrative-documentation>`.
|
