ubuntuusers.de

Sphinx

Dieser Artikel wurde für die folgenden Ubuntu-Versionen getestet:


Du möchtest den Artikel für eine weitere Ubuntu-Version testen? Mitarbeit im Wiki ist immer willkommen! Dazu sind die Hinweise zum Testen von Artikeln zu beachten.

Zum Verständnis dieses Artikels sind folgende Seiten hilfreich:

./sphinx_logo.png 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. Allerdings kann über einige Einstellungen und die Nachrüstung eines Paketes auch Markdown unterstützt werden. Mehr dazu in der offiziellen Dokumentation 🇬🇧. 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.

via pip

Der Python-Paketmanager pip stellt häufig aktuellere Versionen von Programmen als in den Paketquellen bereit. Folgendermaßen lässt sich das Programm darüber installieren:

pip3 install sphinx       # Programm wird nur für den aktuellen Nutzer installiert  

Ab Ubuntu 23.04 muss in eine virtuelle Umgebung für Python installiert werden:

python3 -m venv venv-name && source venv-name/bin/activate # venv-name durch den gewünschten Namen ersetzen
pip3 install sphinx       # Programm ist nur bei aktiver virtueller Umgebung nutzbar  

Hinweis!

Fremdsoftware kann das System gefährden.

Benutzung

Zur Erstellung einer Dokumentation muss zuerst deren Grundgerüst angelegt werden. Dazu bietet Sphinx einen englischsprachigen, text-basierten Assistenten, welcher über den Befehl[2]:

sphinx-quickstart 

aufgerufen wird. Zuallererst wird das aktuelle Verzeichnis als Installationsverzeichnis gewählt, daher sollte in ein eigens dafür angelegtes Verzeichnis gewechselt werden:

mkdir sphinx-test
cd sphinx-test 

Danach werden einige Fragen gestellt.

In der ersten 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 richet sich nach einem Language Code der im Projekt zu verwenden Sprache. Bei Angabe eines validen Codes 🇬🇧 übersetzt Sphinx den generierten Text in die entsprechende Sprache.

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, es sei denn es wurde anderweitig konfiguriert 🇬🇧. 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.

Nun kann man nach dem Wechsel ins Projektverzeichnis die Dokumentation mittels de automatisch angelegten Makefile 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 OPTION(EN) -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, latex 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:

Diese Revision wurde am 26. Juni 2023 17:48 von karzer erstellt.
Die folgenden Schlagworte wurden dem Artikel zugewiesen: Dokumentation, Python, Büro, Programmierung