Personnaliser votre projet Sphinx¶
Il existe deux méthodes principales de personnaliser votre documentation au-delà de ce qu’il est possible avec le noyau Sphinx: les extensions et les thèmes.
Activer une extension intégrée¶
En plus de ses options de configuration, vous pouvez personnaliser Sphinx encore davantage en utilisant des extensions. Sphinx en livre plusieurs intégrées, et il en existe bien plus encore maintenues par la communauté.
Par exemple, pour activer l’extension sphinx.ext.duration, localisez la liste extensions dans votre fichier conf.py et ajoutez un élément comme suit :
# 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',
]
Après cela, chaque fois que vous générez votre documentation, vous verrez un bref rapport de durées à la fin de la sortie sur la console, tel que celui-ci :
(.venv) $ make html
...
The HTML pages are in build/html.
====================== slowest reading durations =======================
0.042 temp/source/index
Utiliser un thème HTML tiers¶
Les thèmes, de leur côté, sont un moyen de personnaliser l’apparence de votre documentation. Sphinx possède plusieurs thèmes intégrés, et il existe aussi des :ref:`thèmes tiers <https://sphinx-themes.org/>`_.
Par exemple, pour utiliser le thème tiers Furo pour votre documentation HTML, vous devrez d’abord l’installer avec pip dans votre environnement virtuel Python, comme ceci :
(.venv) $ pip install furo
Puis, localisez le paramètre html_theme dans votre fichier conf.py, et remplacez sa valeur comme suit :
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'
Avec ce changement, vous constaterez que votre documentation présente une nouvelle apparence :
Documentation HTML de Lumache avec le thème Furo¶
Il est maintenant temps d’étendre le contenu de la documentation et de le séparer en plusieurs documents.