[[Vorlage(Getestet, jammy)]]

{{{#!vorlage Wissen
[:Pakete installieren: Installation von Programmen]
[:Terminal: Ein Terminal öffnen]
[:Editor:Einen Editor benutzen]
}}}
[[Inhaltsverzeichnis()]]

[[Bild(./sphinx_logo.png, 48, align=left)]]
[https://www.sphinx-doc.org/ Sphinx] {en} 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 [http://docutils.sourceforge.net/rst.html reStructuredText] {en} (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 [https://www.sphinx-doc.org/en/master/usage/markdown.html offiziellen Dokumentation] {en}. 
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]).

= Installation =
Sphinx ist in den offiziellen Paketquellen enthalten und kann über das Paket

{{{#!vorlage Paketinstallation
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:

{{{#!vorlage Paketinstallation
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.

{{{#!vorlage 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 ==

[[Vorlage(PipInstallation, sphinx)]]

= 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]:

{{{#!vorlage Befehl
sphinx-quickstart
}}}

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

{{{#!vorlage Befehl
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 [[Vorlage(Tasten,enter)]] 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 [https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language validen Codes] {en} ü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 [https://www.sphinx-doc.org/en/master/usage/configuration.html offiziellen Dokumentation] {en} 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 [https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-source_suffix anderweitig konfiguriert] {en}. 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 [https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-primer ReST Syntax] {en} auch [https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html Sphinx-spezifische Erweiterungen] {en} genutzt werden können.

Besteht die Dokumentation aus mehreren Dokumenten, so sind diese in der Datei '''index.rst''' aufzuführen, und zwar unterhalb der [https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html Toctree-Direktive] {en}. Besteht eine Dokumentation z.B. aus den Dateien '''intro.rst''', '''main.rst''' und '''outro.rst''', dann sollte die Hauptdatei so aussehen:
{{{#!code rst
.. 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:

{{{#!vorlage Befehl
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:

{{{#!vorlage Befehl
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 [https://www.sphinx-doc.org/en/master/usage/builders/index.html offiziellen Dokumentation] {en} 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 [https://www.sphinx-doc.org/en/master/man/sphinx-build.html Man-Page] {en} 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 [#Link 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, [https://www.sphinx-doc.org/en/master/extdev/index.html offizielle Dokumentation] {en}
 * `sphinx-autogen`: [https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html#sphinx-autogen-generate-autodoc-stub-pages offizielle Dokumentation] {en}

= Links =
 * [https://www.sphinx-doc.org/ Projektseite] {en}
  * [github:sphinx-doc/sphinx:Quellcode] {en}
 * [https://readthedocs.org/ Read The Docs] {en} - kostenlose Hosting-Plattform für mit Sphinx generierte Dokumentationen
 * [:docutils:reST] - reStructuredText

#tag: Programmierung, Büro, Python, Dokumentation