Software-Dokumentationen werden oft direkt aus den Kommentaren des Quelltexts erstellt. Das Umwandeln in das gewünschte Zielformat wie HTML oder PDF übernehmen Asciidoc und Sphinx.

Nicht jedem liegt das Schreiben und Pflegen von technischen Dokumenten und Dokumentationen. Es erfordert Beharrlichkeit und Genauigkeit sowie ein Gespür für lesenswerten und verständlichen Text. Da sich zudem Software und die darin eingesetzten Verfahren recht häufig ändern, fällt es schwer, die begleitende Dokumentation synchron zu halten. Mit den beiden Werkzeugen Asciidoc [1] und Sphinx [2] vereinfachen Sie das Erstellen der Anleitungen, indem Sie im oder direkt neben dem Programmcode Dokumentation erstellen.

Asciidoc(tor) [3] sowie Asciidoc FX [4] waren schon des Öfteren Thema in LinuxUser. Jetzt gesellt sich Sphinx der Runde der Werkzeuge hinzu. Es wurde ursprünglich für die Dokumentation von Python entwickelt und kommt heute in fast allen Python-Projekten zum Einsatz [5], etwa bei NumPy, SciPy, Pandas, Matplotlib und SQLAlchemy. Hinzu kommen Projekte außerhalb der Python-Community, wie etwa die Dokumentation des Linux-Kernels [6].

Zur Verbreitung von Sphinx unter den Python-Entwicklern dürfte das Sphinx-Feature Autodoc [7] beigetragen haben, mit dem sich Dokumentationen aus Python-Docstrings erzeugen lassen. Wer möchte, erstellt also aus den Kommentaren im Quelltext die vollständige Dokumentation. Häufig landet sie auch im selben Git-Repository, sodass es keinen gesonderten Aufwand verursacht, die Software-Dokumentation auf dem aktuellen Stand zu halten.

Für Sphinx benötigen Sie keine zusätzlichen Werkzeuge: Es wertet Docstrings [8] mithilfe von Autodoc aus. Letzteres basiert auf speziell formatierten Kommentaren im Python-Code, die sowieso zu jedem guten Skript eines Python-Projekts gehören. Listing 1 zeigt einen solchen Docstring für die Beispielfunktion quadrat(), inklusive Beschreibung, Parameter und Rückgabewert. Docstrings fügen Sie direkt nach dem Funktionskopf ein und umrahmen sie mit dreifachen Anführungszeichen.

def quadrat(faktor):
  """Beschreibung der Funktion
  Parameter:
  faktor (int): übermittelter Zahlenwert
  Ergebnis:
  int:Rückgabewert, hier Quadrat von faktor
  """
  return faktor * faktor

Dokumentenformate

Asciidoc, Asciidoctor und Asciidoctor PDF verwenden als Eingabeformat Markdown [9], Sphinx hingegen nutzt ReStructuredText [10]. Beides schreiben Sie in einem Texteditor Ihrer Wahl. Als Ausgabeformate kommen HTML, PDF, EPUB sowie Manpages infrage.

Sie verwenden eine einfache Syntax mit allen erforderlichen Auszeichnungen für Gliederungsebenen, Absätze, Listen, interne und externe Referenzierungen, Tabellen, Bilder, Graphen, Quellcode mit Syntaxhervorhebung, Fußnoten, Hinweisboxen sowie Glossare und Indizes. Sphinx beherrscht darüber hinaus die Darstellung mathematischer Formeln sowie das Einbinden interaktiver Inhalte in die generierten HTML-Dokumente.

Zur Veranschaulichung für Asciidoc zeigt Listing 2 einen Ausschnitt aus dem Kapitel “Varianten und Formate für Softwarepakete” des Debian-Paketmanagement-Buchs, das die Autoren dieses Artikels betreuen. Der Auszug enthält eine Überschrift für den Abschnitt (Zeile 2) samt Referenz-ID (Zeile 1), Stichworte für den Index (Zeilen 5 bis 7), Textabsätze (Zeilen 8 bis 13) sowie eine Tabelle (Zeilen 15 bis 21) und Abbildungen samt deren Referenz-IDs (Zeile 16). Abbildung 1 zeigt, wie das aus diesem Quelltext erzeugte HTML aussieht.

[[varianten-und-formate-fuer-softwarepakete]]
=== Varianten und Formate für Softwarepakete ===
// Stichworte für den Index
(((Android)))
(((Paketformat, deb)))
(((Paketformat, rpm)))
Auf Linux-Systemen herrscht in Bezug auf das Paketformat keine
Einheitlichkeit. Jede Linux-Distribution legt selbst fest, welches
Paketformat sie verwendet. Zwei dieser Formate haben eine sehr hohe
Verbreitung erlangt - `rpm` und `deb`. Slackware Linux nutzt hingegen
ein schlichtes `tar`-Archiv, welches entweder mit `gzip` oder ab Release
13 mit `xz` komprimiert wird (siehe <<tab.paketformate>>).
.Übersicht zu Paketformaten und deren Verbreitung
[frame="topbot",options="header",id="tab.paketformate"]
|====
| Abkürzung  | Format                 | in Verwendung | Distribution
| `deb`      | Debian-Paketformat     | seit 1993 | Debian, Ubuntu, Grml...
| `rpm`      | Redhat Package Manager | seit 1995 | RedHat/Fedora, CentOS...
|====

Abbildung 1: Ein Ausschnitt mit Überschrift, Absatz und Tabelle aus dem mit Asciidoc erstellten Debian-Paketmanagement-Buch.

Wie bereits erwähnt setzt Sphinx auf ReStructuredText auf. Das nachfolgende Beispiel in Listing 3 zeigt den Abschnitt aus dem Jupyter-Tutorial, der beschreibt, wie Sie ein Jupyter-Notebook erstellen. In den Zeilen 1, 2, 6 und 7 sehen Sie Überschriften unterschiedlicher Gliederungsebenen. Die Zeilen 4 sowie 9 bis 15 enthalten Absätze mit Text. In der Zeile 16 finden Sie einen Verweis auf das Bild initial-notebook.png. Abbildung 2 zeigt, wie ein Webbrowser den Text anzeigt.

Create notebook
===============
After the notebook server has started, we can create our first notebook.
Create a notebook
-----------------
In your standard browser you should see the notebook dashboard with
the *New* menu on the right. All notebook kernels are listed in this
menu, but initially probably only *Python 3*.
After you have selected :menuselection:`New --> Python 3`, a new
notebook ``Untitled.ipynb`` will be created and displayed in a new tab:
.. image:: initial-notebook.png

Abbildung 2: Übersetzter ReStructuredText aus dem Jupyter-Tutorial im Webbrowser.

Installation

Während Asciidoc der GPLv2 unterliegt, greift bei Asciidoctor und Asciidoctor PDF eine MIT-Lizenz. Sphinx verwendet hingegen eine BSD-Lizenz. Erfreulicherweise sind Asciidoc und Sphinx für viele Linux-Distributionen paketiert. Das gilt unter anderem für Debian, Ubuntu, Red Hat und CentOS. Für MacOS finden Sie Pakete in Homebrew und den Macports. Zudem steht der Quellcode auf der jeweiligen Projektwebseite zum Herunterladen bereit. Wie Sie die vier Werkzeuge unter Debian und Ubuntu einrichten, fasst der Kasten “Installation” zusammen.

Beide Werkzeuge weisen eine Reihe von Besonderheiten auf, die sie voneinander abheben. Dazu zählt die Syntaxhervorhebung für Quelltext, der in einem abgesetzten Block im Textfluss erscheint. Asciidoc kennt das Feature nicht, in Asciidoctor und Asciidoctor PDF lässt sich die Funktion mithilfe von Plugins nachrüsten. Dafür stehen Rouge [11], Coderay [12], Pygments [13], Highlight.js [14] und Prism [15] zur Verfügung. Die letzten zwei basieren auf Javascript und passen nur für die Ausgabe als HTML. Alle fünf unterstützen zahlreiche populäre Programmiersprachen.

Nach der Installation des jeweiligen Plugins aktivieren Sie es mithilfe des entsprechenden Schlüsselworts im Asciidoc-Header, für Rouge etwa über :source-highlighter: rouge. Zu einem Quellcodeblock ergänzen Sie dann die Angabe [source, Python], woraufhin Rouge die passende Hervorhebung aktiviert. Listing 4 zeigt einen Block als Beispiel, Abbildung 3 eine Anwendung in der Praxis.

[source, python]
----
print("Hallo Welt!")
----

Abbildung 3: Mit Asciidoc dokumentierter Python-Code. Für die Syntaxhervorhebung sorgt hier Rouge.

Sphinx bietet dasselbe mithilfe des Plugins Pygments. Listing 5 zeigt das an einem Beispiel für eine Python-Funktion. Die Angabe :emphasize-lines: 2 sorgt für eine Hervorhebung der zweiten Zeile. Abbildung 4 zeigt die entsprechende Ausgabe für eine Konfigurationsdatei. Mit der Angabe literalinclude verweisen Sie direkt auf Programmdateien. Ausschnitte davon definieren Sie mit :lines:, Unterschiede mit :diff:.

```
.. code-block:: python
   :emphasize-lines: 2
   def some_function():
      interesting = False
```

Abbildung 4: Die Dokumentation zu einer Konfigurationsdatei mit Hervorhebungen über Pygments/Sphinx.

Die zweite Besonderheit von Sphinx betrifft das Thema Interaktion. So binden Sie für die Ausgabe als HTML-Dokument interaktive Grafiken ein, beispielsweise aus Bokeh. Abbildung 5 zeigt eine Punktmenge in einem zweidimensionalen Koordinatensystem. Über das Lasso oben rechts neben der Abbildung wählen Sie eine Punktemenge aus der Darstellung aus. Diese Punkte erscheinen dann hellrot statt hellblau. Die vollständige Beschreibung dazu finden Sie im PyViz-Tutorial [16].

Abbildung 5: In HTML-Dokumenten lassen sich auch externe Daten einbinden und interaktiv auswählen.

Die dritte Besonderheit heißt Intersphinx [17]. Diese Sphinx-Erweiterung erlaubt das Verlinken auf Objekte in anderen Projektdokumentationen, ohne die spezifische URL angeben zu müssen.

Erweiterungen

Die Liste der Erweiterungen für Asciidoctor [18] und Sphinx [19] ist riesig und sprengt den Rahmen dieses Beitrags. Einen vollständigen Überblick über mitgelieferte und kommerzielle Erweiterungen erhalten Sie auf den jeweiligen Projektseiten.

Eigene Ideen für Erweiterungen lassen sich für Sphinx recht einfach umsetzen. Lokale Erweiterungen in einem Projekt geben Sie relativ zur Dokumentation an. Dazu benennen Sie in der Sphinx-Konfigurationsdatei docs/conf.py den entsprechenden Pfad. Liegt die Erweiterung im Verzeichnis exts/ in der Datei foo.py, dann sieht der Eintrag conf.py so aus wie in Listing 6.

``` python
import sys
import os
sys.path.insert(0, os.path.abspath('exts'))
extensions = [
  'foo',
  [...]
]

Fazit

Die beiden mächtigen Dokumentationssysteme Asciidoc und Sphinx erlauben das Erstellen umfangreicher und aktueller Dokumentationen und deren Export in viele verschiedene Ausgabeformate. Dazu bedarf es allerdings einiger Einarbeitungszeit. Die Autoren nutzen die vorgestellten Systeme für das Verfassen von Schulungsmaterial sowie im Rahmen von ihnen betreuter Projekte wie dem Debian-Paketmanagement-Buch [20] sowie den Tutorials für Jupyter [21] und PyViz [22]. (cla)