Sphinx
Dieser Artikel wurde für die folgenden Ubuntu-Versionen getestet:
Dieser Artikel ist mit keiner aktuell unterstützten Ubuntu-Version getestet! Bitte teste diesen Artikel für eine Ubuntu-Version, welche aktuell unterstützt wird. Dazu sind die Hinweise zum Testen von Artikeln zu beachten.
Zum Verständnis dieses Artikels sind folgende Seiten hilfreich:
Sphinx 🇬🇧 ist ein in Python geschriebenes Programm zum einfachen Erstellen von (umfangreichen) Dokumentationen. Das Programm entstammt zwar dem Python-Umfeld und wird dort auch häufig eingesetzt, ist aber keineswegs darauf beschränkt. Weiterhin sind zur Nutzung von Sphinx keine Python-Kenntnisse notwendig.
Dokumentationen, welche mit Sphinx generiert werden, bestehen aus ein oder mehreren einfachen Textdateien, wobei reStructuredText 🇬🇧 (kurz: reST) als Auszeichnungssprache zum Einsatz kommt. Als Zielformate beherrscht Sphinx standardmäßig HTML und LaTeX, bei Installation der entsprechenden Pakete können auch PDF-Dokumente erzeugt werden (Details siehe folgender Abschnitt Installation).
Installation¶
Sphinx ist in den offiziellen Paketquellen enthalten und kann über das Paket
python3-sphinx
Befehl zum Installieren der Pakete:
sudo apt-get install python3-sphinx
Oder mit apturl installieren, Link: apt://python3-sphinx
installiert werden[1].
Wer aus Sphinx heraus direkt noch fertige PDF-Dokumente generieren möchte, der benötigt noch einen Teil der TeX Live-Pakete:
texlive-latex-recommended
texlive-latex-extra
texlive-fonts-recommended
Befehl zum Installieren der Pakete:
sudo apt-get install texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
Oder mit apturl installieren, Link: apt://texlive-latex-recommended,texlive-latex-extra,texlive-fonts-recommended
Die drei Paket sind recht groß. Es werden 824 MB heruntergeladen; für die Installation werden ca. 1,4 GB Plattenplatz benötigt.
Hinweis:
Die Tex-Live-Pakete sind nur notwendig, wenn direkt aus Sphinx heraus PDF-Dokumente generiert werden sollen. Für die Erstellung von LaTeX-Dokumenten werden diese nicht benötigt.
Benutzung¶
Zur Erstellung einer Dokumentation muss zuerst deren Grundgerüst angelegt werden. Dazu bietet Sphinx einen englischen, text-basierten Assistenten, welcher über den Befehl[2]:
sphinx-quickstart
aufgerufen wird. Danach werden einige Fragen gestellt.
Die erste Frage ist nach dem Installationsverzeichnis. Hier kann ein beliebiges Verzeichnis gewählt werden. Existiert dieses nicht, wird es angelegt. In der zweiten Frage wird gefragt, ob für die Quelldokumente und die erzeugten Dokumente ein jeweils eigenes Verzeichnis angelegt werden soll. Für die Übersichtlichkeit ist dies besser, deshalb ist hier "yes" die bessere Wahl (im Folgenden wird auch davon ausgegangenen, dass dies der Fall ist). Die meisten weiteren Fragen können einfach mit dem Vorgabewert durch Drücken von ⏎ bestätigt werden. Bei der Frage nach dem Projektnamen, dem Autor und der Version müssen jedoch Daten eingegeben werden. Die letzte Frage ist nach einem "Make File". Da dies den Befehlsaufruf zur Generierung der Dokumentation erheblich verkürzt, ist hier die Auswahl von "yes" zweckmäßig, aber natürlich keine Pflicht.
Anschließend legt Sphinx alle benötigten Dateien und Verzeichnisse an. Wichtig sind dabei zwei Dateien, welche sich im Verzeichnis source befinden:
index.rst ist der Ausgangspunkt für die Dokumentation. Diese Datei muss für jedes Projekt existieren.
conf.py enthält die Konfiguration für das gesamte Projekt. Soll diese geändert werden, so kann diese Datei mit einem Editor[3] editiert werden. Details zum Aufbau der Datei sind in der offiziellen Dokumentation 🇬🇧 zu finden.
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 🇬🇧
Links¶
Projektseite 🇬🇧
Quellcode 🇬🇧
Read The Docs 🇬🇧 - kostenlose Hosting-Plattform für mit Sphinx generierte Dokumentationen
reST - reStructuredText