Erste Schritte

Sphinx ist ein Dokumentationsgenerator oder ein Werkzeug, das eine Reihe von einfachen Textquelldateien in verschiedene Ausgabeformate übersetzt und automatisch Querverweise, Indizes usw. erzeugt. Das heißt, wenn Sie ein Verzeichnis mit einer Reihe von reStructuredText- oder Markdown-Dokumenten haben, kann Sphinx eine Reihe von HTML-Dateien, eine PDF-Datei (über LaTeX), Manpages und vieles mehr generieren.

Sphinx konzentriert sich auf Dokumentation, insbesondere auf handschriftliche Dokumentation. Sphinx kann jedoch auch zum Erstellen von Blogs, Homepages und sogar Büchern verwendet werden. Ein Großteil der Leistungsfähigkeit von Sphinx beruht auf der Reichhaltigkeit seines standardmäßigen Klartext-Markup-Formats, reStructuredText, sowie auf seinen erheblichen Erweiterungsmöglichkeiten.

Das Ziel dieses Dokuments ist es, Ihnen einen schnellen Einblick in Sphinx und seine Verwendungsmöglichkeiten zu geben. Wenn Sie hier fertig sind, können Sie das Installationshandbuch und anschließend die Einführung in das von Sphinx verwendete Standard-Markup-Format, reStructuredText, lesen.

Für eine großartige „Einführung“ in das Schreiben von Dokumentation im Allgemeinen – die Warum und Wie – siehe auch Write the docs, geschrieben von Eric Holscher.

Einrichten der Dokumentationsquellen

Das Stammverzeichnis einer Sphinx-Sammlung von reinen Textquelldokumenten wird als Quellverzeichnis bezeichnet. Dieses Verzeichnis enthält auch die Sphinx-Konfigurationsdatei conf.py, in der Sie alle Aspekte konfigurieren können, wie Sphinx Ihre Quellen liest und Ihre Dokumentation erstellt. [1]

Sphinx wird mit einem Skript namens sphinx-quickstart geliefert, das ein Quellverzeichnis einrichtet und eine Standard-conf.py mit den nützlichsten Konfigurationswerten aus einigen gestellten Fragen erstellt. Um dies zu verwenden, führen Sie aus

$ sphinx-quickstart

Definieren der Dokumentenstruktur

Nehmen wir an, Sie haben sphinx-quickstart ausgeführt. Es wurde ein Quellverzeichnis mit conf.py und einem Hauptdokument index.rst erstellt. Die Hauptfunktion des Hauptdokuments besteht darin, als Willkommensseite zu dienen und die Wurzel des „Inhaltsverzeichnisses“ (oder toctree) zu enthalten. Dies ist eines der Hauptmerkmale, die Sphinx zu reStructuredText hinzufügt: eine Möglichkeit, mehrere Dateien zu einer einzigen Hierarchie von Dokumenten zu verbinden.

reStructuredText-Direktiven

toctree ist eine reStructuredText Direktive, ein sehr vielseitiges Markup-Element. Direktiven können Argumente, Optionen und Inhalt haben.

Argumente werden direkt nach dem Doppelpunkt nach dem Namen der Direktive angegeben. Jede Direktive entscheidet, ob sie Argumente haben kann und wie viele.

Optionen werden nach den Argumenten in Form einer „Feldliste“ angegeben. maxdepth ist eine solche Option für die toctree-Direktive.

Inhalt folgt den Optionen oder Argumenten nach einer Leerzeile. Jede Direktive entscheidet, ob sie Inhalt zulässt und was sie damit macht.

Eine häufige Fehlerquelle bei Direktiven ist, dass die erste Zeile des Inhalts auf derselben Ebene eingerückt sein muss wie die Optionen.

Die toctree-Direktive ist anfangs leer und sieht so aus

.. toctree::
   :maxdepth: 2

Sie fügen Dokumente hinzu, indem Sie sie im Inhalt der Direktive auflisten

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

Genau so sieht die toctree für diese Dokumentation aus. Die einzufügenden Dokumente werden als Dokumentennamen angegeben, was kurz bedeutet, dass Sie die Dateiendung weglassen und Schrägstriche (/) als Verzeichnistrenner verwenden.

Siehe auch

Lesen Sie mehr über die toctree-Direktive.

Sie können nun die im toctree aufgeführten Dateien erstellen und Inhalte hinzufügen. Ihre Abschnittsüberschriften werden (bis zur maxdepth-Ebene) an der Stelle eingefügt, an der die toctree-Direktive platziert ist. Außerdem kennt Sphinx nun die Reihenfolge und Hierarchie Ihrer Dokumente. (Sie können selbst toctree-Direktiven enthalten, was bedeutet, dass Sie bei Bedarf tief verschachtelte Hierarchien erstellen können.)

Inhalte hinzufügen

In Sphinx-Quelldateien können Sie die meisten Funktionen des Standard-reStructuredText verwenden. Es gibt auch mehrere von Sphinx hinzugefügte Funktionen. Sie können beispielsweise dateiübergreifende Referenzen auf portable Weise (die für alle Ausgabetypen funktionieren) mit der ref-Rolle hinzufügen.

Als Beispiel: Wenn Sie die HTML-Version betrachten, können Sie die Quelle dieses Dokuments einsehen – verwenden Sie den Link „Show Source“ in der Seitenleiste.

Siehe auch

reStructuredText für eine eingehendere Einführung in reStructuredText, einschließlich des von Sphinx hinzugefügten Markups.

Der Build-Prozess

Nachdem Sie einige Dateien und Inhalte hinzugefügt haben, erstellen wir einen ersten Build der Dokumentation. Ein Build wird mit dem Programm sphinx-build gestartet

$ sphinx-build -M html sourcedir outputdir

wobei sourcedir das Quellverzeichnis ist und outputdir das Verzeichnis, in dem Sie die erstellte Dokumentation platzieren möchten. Die Option -M wählt einen Builder; in diesem Beispiel erstellt Sphinx HTML-Dateien.

Siehe auch

Informationen zu allen Optionen, die sphinx-build unterstützt, finden Sie in der sphinx-build-Manpage.

Sie können auch eine **Live-Version der Dokumentation** erstellen, die Sie im Browser in der Vorschau anzeigen können. Sie erkennt Änderungen und lädt die Seite jedes Mal neu, wenn Sie Bearbeitungen vornehmen. Verwenden Sie dazu sphinx-autobuild, um den folgenden Befehl auszuführen

$ sphinx-autobuild source-dir output-dir

Das Skript sphinx-quickstart erstellt jedoch eine Makefile und eine make.bat, die Ihnen das Leben noch einfacher machen. Diese können durch Ausführen von make mit dem Namen des Builders ausgeführt werden. Zum Beispiel.

$ make html

Dies erstellt HTML-Dokumente im von Ihnen gewählten Build-Verzeichnis. Führen Sie make ohne Argument aus, um zu sehen, welche Ziele verfügbar sind.

Wie generiere ich PDF-Dokumente?

make latexpdf führt den LaTeX Builder aus und ruft die pdfTeX-Toolchain für Sie auf.

Objekte dokumentieren

Eines der Hauptziele von Sphinx ist die einfache Dokumentation von Objekten (im weitesten Sinne) in jeder Domäne. Eine Domäne ist eine Sammlung von Objekttypen, die zusammengehören, komplett mit Markup zur Erstellung und Referenzierung von Beschreibungen dieser Objekte.

Die bekannteste Domäne ist die Python-Domäne. Um beispielsweise die eingebaute Funktion enumerate() von Python zu dokumentieren, würden Sie Folgendes zu einer Ihrer Quelldateien hinzufügen.

.. py:function:: enumerate(sequence[, start=0])

   Return an iterator that yields tuples of an index and an item of the
   *sequence*. (And so on.)

Dies wird wie folgt gerendert

enumerate(sequence[, start=0])

Gibt einen Iterator zurück, der Tupel eines Index und eines Elements der Sequenz liefert. (Und so weiter.)

Das Argument der Direktive ist die Signatur des beschriebenen Objekts, der Inhalt ist die Dokumentation dafür. Es können mehrere Signaturen angegeben werden, jede in einer eigenen Zeile.

Die Python-Domäne ist auch die Standarddomäne, sodass Sie das Markup nicht mit dem Domänennamen präfixieren müssen.

.. function:: enumerate(sequence[, start=0])

   ...

erfüllt denselben Zweck, wenn Sie die Standardeinstellung für die Standarddomäne beibehalten.

Es gibt noch mehrere Direktiven zur Dokumentation anderer Python-Objekttypen, z. B. py:class oder py:method. Es gibt auch eine Rolle zur Querverweisung für jeden dieser Objekttypen. Dieses Markup erstellt einen Link zur Dokumentation von enumerate().

The :py:func:`enumerate` function can be used for ...

Und hier ist der Beweis: Ein Link zu enumerate().

Auch hier kann py: weggelassen werden, wenn die Python-Domäne die Standarddomäne ist. Es spielt keine Rolle, welche Datei die eigentliche Dokumentation für enumerate() enthält; Sphinx findet sie und erstellt einen Link dazu.

Jede Domäne hat spezielle Regeln dafür, wie Signaturen aussehen können, und sorgt dafür, dass die formatierte Ausgabe schön aussieht oder spezifische Funktionen wie Links zu Parametertypen hinzufügt, z. B. in den C/C++-Domänen.

Siehe auch

Domänen für alle verfügbaren Domänen und ihre Direktiven/Rollen.

Grundlegende Konfiguration

Vorhin erwähnten wir, dass die Datei conf.py steuert, wie Sphinx Ihre Dokumente verarbeitet. In dieser Datei, die als Python-Quelldatei ausgeführt wird, weisen Sie Konfigurationswerte zu. Für fortgeschrittene Benutzer: Da sie von Sphinx ausgeführt wird, können Sie darin nicht-triviale Aufgaben ausführen, wie z. B. das Erweitern von sys.path oder das Importieren eines Moduls, um die von Ihnen dokumentierte Version zu ermitteln.

Die Konfigurationswerte, die Sie wahrscheinlich ändern möchten, sind bereits von sphinx-quickstart in conf.py eingefügt und zunächst auskommentiert (mit Standard-Python-Syntax: ein # kommentiert den Rest der Zeile). Um den Standardwert zu ändern, entfernen Sie das Rautezeichen und ändern Sie den Wert. Um einen Konfigurationswert anzupassen, der nicht automatisch von sphinx-quickstart hinzugefügt wird, fügen Sie einfach eine zusätzliche Zuweisung hinzu.

Denken Sie daran, dass die Datei Python-Syntax für Zeichenketten, Zahlen, Listen usw. verwendet. Die Datei wird standardmäßig in UTF-8 gespeichert, wie durch die Kodierungsdeklaration in der ersten Zeile angezeigt.

Siehe auch

Konfiguration für die Dokumentation aller verfügbaren Konfigurationswerte.

Autodoc

Beim Dokumentieren von Python-Code ist es üblich, viel Dokumentation in den Quelldateien, in Docstrings, zu platzieren. Sphinx unterstützt die Einbindung von Docstrings aus Ihren Modulen mit einer Erweiterung (eine Erweiterung ist ein Python-Modul, das zusätzliche Funktionen für Sphinx-Projekte bereitstellt) namens autodoc.

Siehe auch

sphinx.ext.autodoc für die vollständige Beschreibung der Funktionen von autodoc.

Intersphinx

Viele Sphinx-Dokumente, einschließlich der Python-Dokumentation, werden im Internet veröffentlicht. Wenn Sie Links zu solchen Dokumenten aus Ihrer Dokumentation erstellen möchten, können Sie dies mit sphinx.ext.intersphinx tun.

Um Intersphinx zu verwenden, müssen Sie es in conf.py aktivieren, indem Sie den String 'sphinx.ext.intersphinx' in die Liste extensions einfügen und den Konfigurationswert intersphinx_mapping festlegen.

Um beispielsweise auf io.open() im Python-Bibliothekenhandbuch zu verlinken, müssen Sie Ihre intersphinx_mapping wie folgt einrichten

intersphinx_mapping = {'python': ('https://docs.pythonlang.de/3', None)}

Und jetzt können Sie eine Querverweisung wie :py:func:`io.open` schreiben. Jede Querverweisung, die kein passendes Ziel im aktuellen Dokumentensatz hat, wird in den in intersphinx_mapping konfigurierten Dokumentensätzen nachgeschlagen (hierfür ist Zugriff auf die URL erforderlich, um die Liste gültiger Ziele herunterzuladen). Intersphinx funktioniert auch für einige andere Domänen-Rollen, einschließlich :ref:, funktioniert aber nicht für :doc:, da dies eine nicht-domänenbasierte Rolle ist.

Siehe auch

sphinx.ext.intersphinx für die vollständige Beschreibung der Funktionen von intersphinx.

Weitere zu behandelnde Themen

Fußnoten