Dokumentation erstellen¶

Wie bereits erwähnt besteht die Dokumentation minimal aus der Datei index.rst. Bei kurzen Dokumentationen ("single page docs") kann diese komplett in der Datei hinterlegt werden, bei größeren Dokumentationen enthält die Datei die Liste der Dokumente, aus denen die Gesamtdokumentation zusammengesetzt wird.

Alle Dateien sind normale Textdateien, welche mit einem Texteditor angelegt und bearbeitet werden können^[3]. Die Dateinamen müssen keiner bestimmten Konvention folgen, aber die Endung .rst haben. Weiterhin müssen sich alle Dateien im Projektverzeichnis befindet (hier also source).

Der Inhalt der Dokumente wird in der Auszeichnungssprache ReStructuredText geschrieben, wobei neben der üblichen ReST Syntax auch Sphinx-spezifische Erweiterungen genutzt werden können.

Besteht die Dokumentation aus mehreren Dokumenten, so sind diese in der Datei index.rst aufzuführen, und zwar unterhalb der Toctree-Direktive . Besteht eine Dokumentation z.B. aus den Dateien intro.rst, main.rst und outro.rst, dann sollte die Hauptdatei so aussehen:

1
2
3
4
5
6

.. toctree::
   :maxdepth: 2

   intro
   main
   outro

:maxdepth: bestimmt dabei die Tiefe des Inhaltsverzeichnisses (welches Sphinx automatisch generiert); der Wert kann natürlich auch z.B. 1 oder 3 sein.

Dokumente generieren¶

Sind alle rst-Dokumente fertig geschrieben, kann die Dokumentation generiert werden. Dies kann auf zwei Arten geschehen.

Hat man beim Anlegen des Projekts ein Make-File angelegt, dann kann man nach dem Wechsel ins Projektverzeichnis die Dokumentation wie folgt bauen:

make html      # für HTML als Zielformat
make latex     # für LaTeX als Zielformat
make latexpdf  # für PDF als Zielformat 

Wobei der letzte Befehl nur funktioniert, wenn die Tex-Live-Pakete installiert sind.

Der "universellere" Befehl ist der voll manuelle Anstoß des Baus der Dokumentation, die allgemeine Syntax lautet wie folgt:

sphinx-build -b BUILDER QUELLE ZIEL DATEI(EN) 

BUILDER ist einer der Builder, welche Sphinx an Bord hat. Wird -b nicht angegeben, wird HTML als Zielformat genutzt. Eine Übersicht über alle Builder ist in der offiziellen Dokumentation zu finden.

QUELLE ist das Verzeichnis, wo die Datei conf.py liegt. Weiterhin wird hier nach den .rst-Dateien gesucht, wenn keine DATEI(EN) angegeben werden. ZIEL ist das Zielverzeichnis, in dem die generierten Dokumente gespeichert werden. Hat man beim Anlegen des Projekts das Trennen von Quell- und Zieldokumenten gewählt, dann empfiehlt sich für ZIEL das Verzeichnis build. Innerhalb dieses Verzeichnisses gibt es dann wiederum Unterverzeichnisse für die verschiedenen Ausgabeformate, also html, latext usw. PDF-Dateien landen auch im Verzeichnis latex.

Die Angabe von DATEI(EN) ist optional. Werden hier keine Dateien angegeben, werden alle rst-Dateien aus dem Quellverzeichnis herangezogen. Werden Dateien angegeben, werden nur diese für den Bau der Dokumentation genutzt.

Sphinx "bemerkt", ob schon fertige Zieldateien für Quelldateien vorhanden sind und baut diese nicht neu, sofern keine inhaltlichen Änderungen vorliegen. Dies kann aber über die Option -a erzwungen werden.

sphinx-build kennt noch eine Reihe weitere Optionen, welch in der Man-Page erklärt sind.

Weitere Funktionen¶

Die hier beschriebenen Funktionen von Sphinx stellen nur dessen Grundfunktionalität dar, das System kann noch weit mehr. Ein vollständiger Überblick ist in der offiziellen Dokumentation zu finden, siehe Abschnitt Links.

Weitere Programme¶

Neben den hier beschriebenen Programmen aus dem Sphinx-Paket werden noch zwei weitere installiert:

• sphinx-apidoc: dient zu automatisierten API-Dokumentation von kompletten Python-Modulen, offizielle Dokumentation

• sphinx-autogen: offizielle Dokumentation