Sphinx-Quickstart

Um ein neues Sphinx-Projekt zu starten, kann man entweder einen bestehenden Projekt-Ordner kopieren und modifizieren, oder ein neues Verzeichnis anlegen und in diesem mittels der Shell-Anweisung sphinx-quickstart ein neues Grundgerüst erstellen:

# Projekt-Verzeichnis anlegen
mkdir projektordner
cd projektordner

# Neues Sphinx-Projekt starten:
sphinx-quickstart

Sphinx erstellt daraufhin einige notwendige Hilfsdateien, beispielsweise eine Makefile und eine Konfigurationsdatei namens conf.py, in der auch zu einem späteren Zeitpunkt Einstellungen für das jeweilige Projekt festgelegt werden können.

Beim Aufruf von sphinx-quickstart erscheinen zunächst einige Benutzer-Abfragen, mit denen der Name des Projekts sowie andere grundlegende Einstellungen vorgenommen werden können:

  • Bei der ersten Abfrage soll der Nutzer angeben, in welchem Pfad das Projekt initiiert werden soll. Üblicherweise startet man sphinx-quickstart bereits im Projekt-Verzeichnis, so dass kein expliziter Pfad angegeben werden muss, sondern die Vorgabe [.] durch Drücken der Enter-Taste bestätigt werden kann:
Welcome to the Sphinx 1.6.2 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]:

  • Bei den beiden nächsten Abfragen geht es darum, ob für die Quelldateien ein eigener Ordner angelegt werden soll und wie besondere Ordner, die beispielsweise Logos oder Templates beinhalten, gekennzeichnet werden sollen. Bei beiden Fragen sind meiner Meinung nach die Standard-Vorgaben empfehlenswert, es genügt somit jeweils eine Bestätigung mit der Enter-Taste.

    Die Quelltexte der Webseite werden bei diesen Standard-Einstellungen im Projektverzeichnis beziehungsweise in Unterverzeichnissen abgelegt; der von Sphinx erzeugte HTML- beziehungsweise LaTeX-Code wird hingegen in die separaten Unterverzeichnisse _build/html beziehungsweise _build/latex geschrieben.

  • Bei den nächsten Abfragen muss der Projekt- sowie der Autorname der Dokumentation angegeben werden; die Angabe einer Versionsnummer ist optional und kann auch zu einem späteren Zeitpunkt in der Konfigurationsdatei conf.py vorgenommen werden.

    Als Sprache kann wahlweise en für Englisch, de für Deutsch, oder ein anderes Sprach- beziehungsweise Länderkürzel gesetzt werden (eine Übersicht über die unterstützten Sprachen gibt es hier).

  • Bei den beiden nächsten Abfragen wird eine Datei-Endung für die Quelltext-Dateien sowie der Name der grundlegenden Index-Datei festgelegt. Auch hier ist es empfehlenswert die jeweiligen Vorgaben mit der Enter-Taste zu bestätigen.

    Die Datei index.rst im Projekt-Verzeichnis beinhaltet im Wesentlichen ein Inhaltsverzeichnis („toctree“), welcher die Einhänge-Punkte der übrigen Quelltext-Dateien festlegt.

  • Bei der nächsten Abfrage wird festgelegt, ob ein Epub-Builder gewünscht ist oder nicht. Gewöhnlich kann hier die Vorgabe [n] mit der Enter-Taste bestätigt werden.

  • Bei der nächsten Abfrage kann man festlegen, welche Sphinx-Module für das Dokumentations-Projekt genutzt werden sollen; die Auswahl kann ebenfalls später in der Konfigurationsdatei conf.py überarbeitet werden.

    Bei mir persönlich würde die Modul-Abfrage folgendermaßen ausfallen:

    > autodoc: y

    Dieses Modul ist für die Dokumentation von Python-Programmen gedacht – hierbei kann eine Dokumentation automatisch anhand der Docstrings der jeweiligen Funktionen beziehungsweise Module erstellt werden.

    > doctest: n

    Python ermöglicht es, in die Docstrings von Funktionen Tests einzubauen. Ich persönlich verwende lieber Unittests und nutze dieses Feature daher nicht.

    > intersphinx: y

    Intersphinx-Mappings ermöglichen es, von einer Sphinx-Dokumentation aus auf andere Sphinx-Dokumentationen zu verweisen.

    Hierbei wird in der Konfigurationsdatei conf.py unter dem Begriff intersphinx_mapping festgelegt, welche externen Projekte mit welchem Kürzel genutzt werden sollen. Ein solcher Eintrag könnte beispielsweise wie folgt aussehen:

    intersphinx_mapping = {
    'sphinx': ('http://www.sphinx-doc.org/en/stable', None),
    'gwm': ('http://grund-wissen.de/mathematik', None),
    'gwp': ('http://grund-wissen.de/physik', None),
}

    Innerhalb der Dokumentation kann dann beispielsweise mittels :ref:`Mechanik <gwp:Mechanik> auf den Mechanik-Teil der Physik-Dokumentation im Grund-Wissen-Projekt verwiesen werden.[1]

    > todo: n

    Dieses Modul ermöglicht es, Todo-Notizen in die Dokumentation aufzunehmen eine Übersichtsliste daraus zu erstellen. Persönlich vermerke ich mir Todos allerdings lieber als Kommentare, die dann im fertigen Dokument nicht erscheinen.

    > coverage: n

    Dieses Modul ist ebenfalls für die Dokumentation von Python-Programmen gedacht, und ermöglicht eine Anzeige, wie viele der definierten Funktionen bereits über eine Dokumentation (einen Docstring) verfügen.

    > imgmath: y

    Bei Verwendung dieses Moduls werden mathematische Formeln für die HTML-Version als png-Dateien gerendert; diese werden dann an den jeweiligen Stellen automatisch eingefügt.

    Diese Option hat als Nachteil, dass bei technischen Dokumentationen unter Umständen viele (sogar tausende) png-Dateien erstellt werden, was ein Hochladen des Projekts auf den Webserver verlangsamt. Der Vorteil ist hingegen, dass die Anzeige im Webbrowser auch ohne zusätzliche Javascript einwandfrei funktioniert.

    > mathjax: n

    Bei Verwendung dieses Moduls werden mathematische Formeln in der HTML-Version so ausgegeben, dass sie erst im Browser des Lesers mittels Javascript gerendert werden.

    Je nach Vorlieben sollte man sich entweder für die imgmath- oder für die mathjax-Option entscheiden.

    > ifconfig: n

    Dieses Modul ermöglicht es, bestimmte Inhalte nur dann in der Dokumentation zu berücksichtigen, wenn entsprechende Konfigurationen in der Datei conf.py vorliegen. Persönlich habe ich dieses Feature bislang nicht benötigt.

    > viewcode: y

    Dieses Modul ermöglicht es, die Dokumentation von (Python-)Quellcode mit den jeweiligen Stellen des Quellcodes selbst zu verknüpfen; dies ist für die Dokumentation von Open-Source-Programmen durchaus nützlich.

  • Bei der letzten Abfrage gibt man an, ob eine Makefile (für Linux-Systeme) oder eine Commandfile (für Windows-Systeme) angelegt werden soll; diese Entscheidung muss je nach eingesetztem Betriebsystem individuell getroffen werden.

Anschließend wird das Projekt von Sphinx fertig angelegt und kann beliebig gestaltet beziehungsweise mit Inhalten gefüllt werden.

Regulärer Aufruf von Sphinx

Ein bestehendes Projekt (beispielsweise ein selbst erstelltes oder ein von Github geclontes) kann auf einfache Weise als Webseite oder PDF-Datei ausgegeben werden. Hierzu wechselt man in einer Shell in das Projekt-Verzeichnis und gibt folgendes ein:

# HTML-Dateien erzeugen:
make html

# LaTeX-Code erzeugen:
make latex

# LaTeX-Code erzeugen und daraus eine PDF-Datei erstellen:
make latexpdf

Treten aufgrund einer fehlerhaften RST-Syntax während des Übersetzens Fehler auf, so werden diese mit einer kurzen Erläuterung und der Angabe der den Fehler verursachenden Stelle auf dem Bildschirm ausgegeben.

Die neu erstellten Dateien werden vons sphinx bei Verwendung der oben genannten Konfiguration im _build-Verzeichnis innerhalb des Projektpfads abgelegt. Je nach Ausgabe-Variante können die erstellten folgendermaßen aufgerufen werden:

# Erstellte HTML-Seiten mit Webbroswer "firefox" öffnen:
firefox _build/html/index.html

# Erstellte PDF-Datei mit PDF-Betrachter "evince" öffnen:
evince _build/latex/projekttitel.pdf

Der Name des PDF-Dokuments wird in der Konfigurationsdatei conf.py unter der Rubrik latex_documents festgelegt.

Um den bestehenden Build eines Projekts zu entfernen, beispielsweise nach einem Umbenennen mehrerer Quelldateien oder einer neuen Ordnerstruktur, kann Folgendes eingegeben werden:

make clean

Anschließend können mittels make html, make latex oder make latexpdf neue Builds erstellt werden.

Projekt auf nicht funktionierende Links prüfen

Auf folgende Weise kann ein bestehendes Projekt hinsichtlich nicht funktionierender Web-Links überprüft werden:

make linkcheck

Dieser Aufruf gibt auf dem Bildschirm alle Links zu nicht mehr existierenden oder permanent umgeleiteten Seiten aus. Dieses Feature sollte in regelmäßigen Abständen genutzt werden, um den Besuchern der Seite unnötige 404: Seite nicht gefunden-Fehlermeldungen zu ersparen; auch Suchmaschinen werten einen möglichst hohen Anteil an funktionierenden Links als Kriterium für die Aktualität einer Seite.

Intersphinx-Mappings aktualisieren

Bei der Verwendung von Sphinx ist es möglich, Links auf Begriffe aus anderen Sphinx-Dokumentationen zu setzen; dies wird als Intersphinx-Mapping bezeichnet.

Mit den normalen Einstellungen werden die Index-Kataloge der angegebenen Projekte nur beim erstmaligen Erstellen eines Projekts geladen. Kommen bei den externen Projekten weitere Begriffe hinzu, so kann also nur dann mittels eines Intersphinx-Mappings darauf verwiesen werden, wenn explizit geprüft wird, ob sich Änderungen in den angegebenen Projekten ergeben haben. Dies kann durch folgende Änderung in der Makefile des Projekts erreicht werden:

# Original
# SPHINXOPTS =

# Intersphinx-Seiten auf Änderungen prüfen:
SPHINXOPTS = -E

Durch die ergänzende Angabe der Option -E werden beim Aufruf von make html, make latex oder make latexpdf alle externen Index-Kataloge neu eingelesen. Dies kann den Übersetzungs-Prozess erheblich verlangsamen und sollte daher nur bei Bedarf temporär geändert werden.

Sphinx-Autobuild

Mit dem Paket Sphinx-Autobuild kann erreicht werden, dass die HTML-Ausgabe einer Dokumentation automatisch aktualisiert wird, sobald eine .rst-Quelltext-Datei innerhalb des Projekt-Ordners angelegt/verändert wird.

Das Paket kann folgendermaßen installiert werden:

# Installation:
pip3 install sphinx-autobuild

Der Aufruf erfolgt dann beispielsweise wie folgt:

# Sphinx-Autobuild aufrufen:
sphinx-autobuild . _build/

Im obigen Fall würde das aktuelle Verzeichnis (.) als Quell- und das Verzeichnis _build als Zielverzeichnis für die HTML-Ausgabe verwendet.

Zusätzlich zu den Optionen von sphinx-build, die ebenfalls mit sphinx-autobuild genutzt werden können, gibt es allgemein folgende zusätzlichen Optionen:

  • -H: Host-Adresse des Webservers (Standard: 127.0.0.1)
  • -p: Port angeben, auf dem der Webserver erreichbar ist (Standard: 8000)
  • -B: Automatisch den Standard-Webbrowser mit der Projekt-URL öffnen
  • -i: | Dateien (auch Wildcards) angeben, deren Änderungen ignoriert werden sollen.

Sphinx-Autobuild bleibt als laufender Prozess im Shell-Fenster geöffnet, achtet auf Änderungen

Nach einem fertigen Build wird automatisch ein Webserver gestartet, der über die Hostadresse 0.0.0.0 und den Port 8888 erreichbar ist. Mittels der Option -B wird die Index-Seite des Projekts automatisch im Standard-Webbrowser geöffnet.

# Beispiel-Aufruf: sphinx-autobuild -B . _build/

Einzelne Dateien mit rst2latex konvertieren

Hat man unter Linux das Paket python3-docutils installiert, so stehen neben Sphinx auch die Konverter rst2html und rst2latex zur Verfügung, die jeweils eine einzelne Quelldatei in ein HTML- beziehungsweise LaTeX-Dokument übersetzen.

Für die Verwendung von rst2latex habe ich mir eine Makefile mit folgendem Inhalt gebastelt:

# Datei: rstmakefile

%: %.rst
    rst2latex $< > $*.tex
    pdflatex $*.tex
    rm $*.aux $*.log $*.out

In einer Shell kann man dann im Projektordner folgendermaßen aus einer .rst-Datei eine gleichnamige .tex-Datei sowie das zugehörige .pdf-Dokument erzeugen:

# RST-Datei dateiname.rst konvertieren:
# (Dateiendung dabei weglassen!)
make -f pfad-zur-rstmakefile dateiname

# Ergebnis: dateiname.tex, dateiname.pdf

Diese Methode hat zwei sehr schöne Nebeneffekte: Erstens wird, anders als bei Verwendung von Sphinx, ein „klassischer“ LaTeX-Code ohne Extra-Konfigurationen und besonderen Stil-Elementen generiert. Zweitens können über die Konfigurationsdatei ~/.docutils optional zusätzliche Pakete in die LaTeX-Präambel geladen werden, um beispielsweise das Seitenlayout anzupassen. Meine Konfigurationsdatei hat beispielsweise folgenden Inhalt:

[latex2e writer]
latex_preamble: \usepackage{units,amsmath,amsfonts,amssymb,textcomp,gensymb,marvosym,wasysym}
                \usepackage[left=2cm,right=2cm,top=1cm,bottom=1.5cm]{geometry}
                \setlength{\parskip}{\baselineskip} % Extra line between paragraphs
                \setlength{\parindent}{0pt} % No indent at the start of paragraphs
                \pagestyle{empty}

Durch diese Einstellungen werden einerseits Zusatz-Pakete für mathematischen Formelsatz eingebunden, zum anderen werden durch das geometry-Paket die Seitenränder auf ein Minimum reduziert, so dass beim Drucken einzelner Notiz-Seiten kein Platz verschwendet wird.

Anmerkung:

[1]

Die Angaben können zu jedem späteren Zeitpunkt in der Konfigurationsdatei conf.py geändert werden.

Durch die Vergabe von Versionsnummern kann beispielsweise bei der Dokumentation von Software-Quellcode sichergestellt werden, dass eine Anleitung auch zur jeweiligen Software-Version passt. Auch bei allgemeinen Dokumentationsprojekten ist eine Versionsnummer sinnvoll, um den jeweiligen Entwicklungsstand aufzuzeigen; mit einem Versions-Upgrade können außerdem eine Rundmail über einen Verteiler, ein neuer Commit eines Versionsverwaltungs-Programms, ein Weblog-Eintrag o.ä. verbunden werden.
[2]Im Abschnitt Sprungmarken und Referenzen. ist dies näher beschrieben.