Narrative Dokumentation in Sphinx¶
Strukturieren Ihrer Dokumentation über mehrere Seiten¶
Die von sphinx-quickstart erstellte Datei index.rst ist das Stammdokument, dessen Hauptfunktion darin besteht, als Willkommensseite zu dienen und die Wurzel des „Inhaltsverzeichnisses“ (oder toctree) zu enthalten. Sphinx ermöglicht es Ihnen, ein Projekt aus verschiedenen Dateien zusammenzustellen, was hilfreich ist, wenn das Projekt wächst.
Erstellen Sie als Beispiel eine neue Datei docs/source/usage.rst (neben index.rst) mit diesem Inhalt
Usage
=====
Installation
------------
To use Lumache, first install it using pip:
.. code-block:: console
(.venv) $ pip install lumache
Diese neue Datei enthält zwei Abschnitts-Überschriften, normalen Absatztext und eine code-block-Direktive, die einen Inhaltsblock als Quellcode rendert, mit entsprechender Syntaxhervorhebung (in diesem Fall generischer console-Text).
Die Struktur des Dokuments wird durch die Abfolge von Überschriftenstilen bestimmt. Das bedeutet, dass Sie durch die Verwendung von --- für den Abschnitt „Installation“ nach === für den Abschnitt „Usage“ „Installation“ als Unterabschnitt von „Usage“ deklariert haben.
Um den Vorgang abzuschließen, fügen Sie am Ende von index.rst eine toctree Direktive hinzu, die das gerade erstellte Dokument wie folgt einbindet:
Contents
--------
.. toctree::
usage
Dieser Schritt fügt dieses Dokument in die Wurzel des toctree ein, sodass es nun zur Struktur Ihres Projekts gehört, die bisher so aussieht:
index
└── usage
Wenn Sie die HTML-Dokumentation mit make html erstellen, sehen Sie, dass der toctree als Liste von Hyperlinks gerendert wird, und dies ermöglicht Ihnen die Navigation zur neu erstellten Seite. Nett!
Warnung
Dokumente außerhalb eines toctree führen während des Build-Prozesses zu Nachrichten wie WARNUNG: Dokument ist nicht in einem toctree enthalten und sind für Benutzer nicht erreichbar.
Hinzufügen von Querverweisen¶
Eine mächtige Funktion von Sphinx ist die Möglichkeit, nahtlos Querverweise zu bestimmten Teilen der Dokumentation hinzuzufügen: ein Dokument, ein Abschnitt, eine Abbildung, ein Code-Objekt usw. Dieses Tutorial ist voll davon!
Um einen Querverweis hinzuzufügen, schreiben Sie diesen Satz direkt nach dem Einführungsparagraphen in index.rst
Check out the :doc:`usage` section for further information.
Die verwendete doc Rolle verweist automatisch auf ein bestimmtes Dokument im Projekt, in diesem Fall auf die zuvor erstellte usage.rst.
Alternativ können Sie auch einen Querverweis zu einem beliebigen Teil des Projekts hinzufügen. Dafür müssen Sie die ref-Rolle verwenden und eine explizite Beschriftung hinzufügen, die als Ziel dient.
Um beispielsweise auf den Unterabschnitt „Installation“ zu verweisen, fügen Sie direkt vor der Überschrift eine Beschriftung hinzu, wie folgt:
Usage
=====
.. _installation:
Installation
------------
...
Und lassen Sie den Satz, den Sie in index.rst hinzugefügt haben, wie folgt aussehen:
Check out the :doc:`usage` section for further information, including how to
:ref:`install <installation>` the project.
Beachten Sie hier einen Trick: Der Teil install gibt an, wie der Link aussehen soll (wir möchten, dass es ein bestimmtes Wort ist, damit der Satz Sinn ergibt), während der Teil <installation> auf die eigentliche Beschriftung verweist, zu der wir einen Querverweis hinzufügen möchten. Wenn Sie keinen expliziten Titel angeben und somit :ref:`installation` verwenden, wird der Abschnittstitel verwendet (in diesem Fall Installation). Sowohl die :doc: als auch die :ref: Rollen werden in der HTML-Dokumentation als Hyperlinks gerendert.
Was ist mit dem Dokumentieren von Code-Objekten in Sphinx? Lesen Sie weiter!