Mehr Sphinx-Anpassungen¶
Es gibt zwei Hauptwege, Ihre Dokumentation über die Möglichkeiten des Kerns von Sphinx hinaus anzupassen: Erweiterungen und Themes.
Eine integrierte Erweiterung aktivieren¶
Zusätzlich zu diesen Konfigurationswerten können Sie Sphinx noch weiter anpassen, indem Sie Erweiterungen verwenden. Sphinx wird mit mehreren integrierten Erweiterungen geliefert, und es gibt viele weitere, die von der Community gepflegt werden.
Um beispielsweise die Erweiterung sphinx.ext.duration zu aktivieren, suchen Sie die Liste extensions in Ihrer conf.py und fügen Sie wie folgt ein Element hinzu:
# 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',
]
Danach wird jedes Mal, wenn Sie Ihre Dokumentation generieren, am Ende der Konsolenausgabe ein kurzer Bericht über die Dauer angezeigt, wie dieser:
(.venv) $ make html
...
The HTML pages are in build/html.
====================== slowest reading durations =======================
0.042 temp/source/index
Verwendung eines externen HTML-Themes¶
Themes hingegen sind eine Möglichkeit, das Erscheinungsbild Ihrer Dokumentation anzupassen. Sphinx verfügt über mehrere integrierte Themes, und es gibt auch externe Themes.
Um beispielsweise das externe Theme Furo für Ihre HTML-Dokumentation zu verwenden, müssen Sie es zuerst mit pip in Ihrer virtuellen Python-Umgebung installieren, wie hier:
(.venv) $ pip install furo
Suchen Sie dann die Variable html_theme in Ihrer conf.py und ersetzen Sie ihren Wert wie folgt:
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'
Mit dieser Änderung werden Sie feststellen, dass Ihre HTML-Dokumentation nun ein neues Erscheinungsbild hat.
HTML-Dokumentation von Lumache mit dem Furo-Theme¶
Nun ist es an der Zeit, die narrative Dokumentation zu erweitern und in mehrere Dokumente aufzuteilen.