Dokumentation schreiben mit reStructuredText (RST)

Wie man Dokumentation mit reStructuredText (RST) schreibt und welche Tools das Leben erleichtern

Momentan überarbeite ich meine private Serverdokumentation und möchte sie Stück für Stück dann auch hier im Blog veröffentlichen. Zum einen, um das dank zahlreicher Quellen gelernte Wissen wieder weiterzugeben, zum anderen, um Anregungen und Verbesserungsvorschläge zu sammeln.

Den Anfang macht dabei ein Meta-Thema, nämlich die Frage, wie die eigentliche Dokumentation aufgebaut ist. Ich setze dabei auf reStructuredText (RST), das ich im Folgenden kurz vorstellen möchte. Tools für die Dokumentation gibt es zahlreiche, für meine Zwecke sollte es explizit etwas Einfaches sein, das ich lokal nutzen kann.

Was ist reStructuredText?

Schlussendlich bin ich auf reStructuredText (RST) gestoßen, einer einfachen Auszeichnungssprache, die ich lokal im Editor bearbeite und dann beispielsweise ins HTML- oder PDF-Format konvertieren kann. Die grundlegende Syntax ist simpel und für größere Anforderungen gibt es auch die Möglichkeit, die Dokumente beispielsweise in einem Git-Repository abzulegen. Jemand, der professionell Dokumentation schreibt oder im Team arbeitet, mag ganz andere Anforderungen haben als ich, für meine Zwecke ist RST jedoch ideal geeignet.

Ein paar Tools

Als Editor setze ich dabei auf Sublime Text, der sich dank Package Control um zahlreiche Plugins erweitern lässt. Konkret installiert habe ich Restructured Text (RST) Snippets und RestructuredText Improved, die mir bei der Bearbeitung der Dokumente zur Seite stehen. Zur Konvertierung ins HTML-Format nutze ich rst2html, das ich unter Mac OS X ganz einfach mit

pip install rst2html5

installiert habe. Spätere Updates lassen sich dann mit

pip install --upgrade pip
pip install --upgrade rst2html

einspielen. Die Konvertierung des fertigen Dokuments geht mit folgendem Einzeiler vonstatten:

rst2html5 --time --toc-top-backlinks quelldatei.rst zieldatei.html

Unter Linux habe ich das Ganze noch nicht getestet, hier scheint aber das Paket python3-docutils das Mittel der Wahl zu sein; die Kommandozeile fängt dann leicht abgewandelt mit rst2html (ohne Versionsangabe) an.

In größeren Umgebungen gibt es zudem die Möglichkeit, ein Dokument per Git-Hook automatisch zu konvertieren, sobald es eingecheckt wurde. Interessant ist auch das Angebot von Read the Docs, das die automatische Erstellung von durchsuchbaren Dokumentationen auf Basis eines Git-Repositories ermöglicht.

Sprachelemente

Doch wie sieht das Format genau aus? RST kommt mit einer Vielzahl von Elementen, um die eigenen Dokumente zu strukturieren. Im Folgenden stelle ich die für mich relevanten vor.

Dokumentstruktur

Der Dokumenttitel wird durch das Gleichheitszeichen markiert:

Serverdokumentation
===================
Dieses Dokument beschreibt die Installation meines Servers.

Einzelne Absätze werden durch einen Bindestrich gekennzeichnet:

Voraussetzungen
---------------
Im Folgenden finden sich die Systemvoraussetzungen.

Konventionen
------------
Dieses Dokument folgt bestimmten Konventionen, die hier genannt sind.

Eine weitere Überschriftsebene lässt sich mit dem Pluszeichen darstellen:

Voraussetzungen
---------------
Im Folgenden finden sich die Systemvoraussetzungen.

Software
++++++++
Folgende Software wird benötigt:

Hardware
++++++++
Diese Hardware wird unterstützt:

Textauszeichnungen

RST beherrscht auch die üblichen Textauszeichnungen:

Dieses Wort wird `kursiv` dargestellt.
**Dieser Text erscheint fett.**
Um den Server neu zu starten, geben Sie ``shutdown -r now`` ein.

Aufzählungen

Aufzählungen werden im RST-Format einfach mit einem Spiegelstrich eingeläutet. Um einzelne Elemente einzurücken, muss einfach die entsprechende Zeile eingerückt werden:

- ``befehl 1``
- **Wichtiger** Hinweis
- Die folgenden Befehle benötigen etwas Zeit:

  - ``befehl 2``
  - ``befehl 3``
  - ``befehl 3``

- Jetzt geht es hier weiter

Listings

Programmcode oder längere Kommandozeilen lassen sich als Listing darstellen:

::

cat >> ~/tagebuch.txt << EOF
30. April: Wochenende!
1. Mai: Ich schreibe eine Dokumentation
EOF

Das Ganze kann auch mit Auflistungen kombiniert werden:

- erster Punkt
- **wichtiger zweiter** Punkt
- `kursiver` dritter Punkt
- bitte ``uname -a`` eingeben
- ::

   cat >> ~/tagebuch.txt << EOF
   30. April: Wochenende!
   1. Mai: Ich schreibe eine Dokumentation
   EOF

Fußnoten

Auch Fußnoten werden unterstützt. Dazu einfach an der Stelle im Dokument, an der die Fußnote erscheinen soll, Folgendes schreiben:

Weitere Informationen finden Sie auf der entsprechenden Webseite. [2]_

Am Ende des Dokuments werden die Fußnoten dann gesammelt:

.. [1] Erste Fußnote
.. [2] Zweite Fußnote

Hinweise

Bei einigen der oben genannten Beispiele ist die exakte Einrückung wichtig, sonst verweigerte zumindest bei mir rst2html seinen Dienst. Beispielsweise müssen Listings, die auf :: folgen, sowohl mit einer Leerzeile eingeläutet als auch auf die Position des zweiten Doppelpunkts eingerückt werden. Gleichsam müssen Einrückungen bei Aufzählungen per Leerzeile beginnen und um drei Zeichen eingerückt werden.