Alles im Griff
Projektdokumentation mit reStructuredText und Sphinx
reStructuredText
Wegen der vielen Markup-Optionen und ihrer Ökosysteme ist es eine Geschmacks- und Glaubensfrage, für welche Lösung man sich entscheidet. Für den Autor ist das aus der Python-Welt stammende reStructuredText (reST) ein klarer Favorit.
Python-Projekte verwenden es neben der Dokumentation von Software-Modulen und darauf basierenden Applikationen auch für Kommentare im Quellcode. Ähnlich wie bei dem Tool Doxygen lassen die sich dann automatisiert extrahieren, um zum Beispiel eine API-Dokumentation für Entwickler zu erzeugen. Mit Hilfe des Tools pydoc ist das auch on-the-fly möglich. Für reST spricht weiterhin, das eine sehr aktive Entwicklergemeinde es weiterentwickelt, und dass es große Verbreitung auch außerhalb der Python-Community besitzt. Das Docutils-Projekt von Python ist Hüter der Markup-Sprache und bietet neben einer Python-Bibliothek zur Verarbeitung von reST-Dokumenten eine Reihe von Werkzeugen an, mit denen sich reStructuredText in die verschiedensten Ausgabeformate konvertieren lässt.
Ein in reST formatierter Dokument-Quelltext ist auch ohne speziellen Editor gut lesbar und selbst im Rohformat fast druckreif, wie das Beispiel in der Abbildung zeigt.
){kind=small}
Lenz Grimmer
Quasi druckreif: Code-Beispiel für reStructuredText
Rund um das Markup hat sich mittlerweile ein großes Ökosystem aus Anwendungen und Tools gebildet. So wandelt beispielsweise das Werkzeug odt2rst Dokumente aus Libre Office oder Openoffice.org in das reST-Format um. Die Ergebnisse hängen zwar stark von den im Originaldokument verwendeten Auszeichnungen und Formatierungen ab und müssen meist noch nachbearbeitet werden. Aber mitunter ist eine solche Konvertierung der schnellere Weg, als Inhalte per Cut & Paste aus einem Office-Dokument zu übertragen.
Auch die Erstellung von Präsentationen in reST geht mit Werkzeugen wie Hovercraft oder Landslide recht gut von der Hand. Die daraus generierten Folien sind dank der Javascript-Bibliothek impress.js (Hovercraft) und der Verwendung von HTML5 (Landslide) optisch sehr ansprechend. Die Python-basierte Software Nikola erzeugt auf Basis von reST-Dokumenten Blogs oder ganze Websites, die dank ihrer statischen Natur sehr performant sind und sich quasi überall ohne viel Aufwand hosten lassen. reStructuredText hat sich also auch außerhalb des Kontexts der Projektdokumentation gut etabliert.
Sphinx
Um nun aber aus einzelnen Dateien mit reST-Markup eine ansprechende und strukturierte Dokumentation zu erzeugen, bedarf es eines darauf aufsetzenden Frameworks. Ein populärer Vertreter dieser Gattung ist Sphinx.
Es ermöglicht, auch komplexere Dokumente bestehend aus mehreren reST-Dateien zu strukturieren, zu verwalten und sie automatisiert in diversen Ausgabeformaten auszugeben. Es entstand ursprünglich für die Pflege und Verwaltung der Python-Dokumentation auf http://docs.python.org/ und befindet sich weiterhin in aktiver Entwicklung. Von Haus aus unterstützt Sphinx die gängigen Ausgabeformate HTML, PDF und ePub. Die Erweiterung um andere Formate ist relativ einfach. Layout und Aussehen der fertigen Dokumente lässt sich mit Templates anpassen. Praktisch bei der HTML-Ausgabe ist die eingebaute Suchmaschine, die mit Javascript schnelles Durchsuchen eines Dokuments ermöglicht und auf Seiten des Webservers keinerlei Skriptsprachen oder andere Besonderheiten erfordert.
Sphinx erweitert die reStructuredText-Markup-Sprache um weitere Elemente, zum Beispiel das Einfügen von Querverweisen auf andere Dokumente oder automatisiert erzeugte hierarchische Strukturen wie Inhaltsverzeichnisse („toctrees“), Fußnoten und Glossare. Weitere Sphinx-spezifische reST-Konstrukte ermöglichen das Einfügen von dokumentationsspezifischen Elementen wie Info- und Warnboxen, Code-Beispiele mit farbigem Syntax-Highlighting und die automatische Substitution häufig vorkommender Text-Elemente wie Produktnamen.
Die umfangreiche und gut strukturierte Dokumentation bietet auch Anfängern einen leichten Einstieg. Bei Problemen findet sich schnell eine Antwort - Sphinx hat eine aktive und hilfreiche Community. Die Web-Plattform ReadTheDocs hostet öffentlich mit Sphinx generierte Dokumentationen aus der Community und bietet unter anderem die Möglichkeit, Querverweise auf andere dort gehostete Dokumente in die eigene Dokumentation einzubetten.
Wo viel Licht ist, ist natürlich auch Schatten. Es gibt auch bei Sphinx das ein oder andere »Gotcha!«, das einem Autor Kopfzerbrechen bereitet. Zu den Klassikern zählt sicher die gemischte Verwendung von Tabs und Leerzeichen im reST-Quellcode. Ähnlich wie bei Python dienen an vielen Stellen Einrückungen dazu, den Inhalt zu strukturieren. Wenn dafür nicht konsequent die gleichen Steuerzeichen verwendet werden, ist das Resultat mitunter überraschend, obwohl es im Quelltext auf den ersten Blick korrekt aussieht. Dies ist insbesondere bei Projekten mit vielen Entwicklern - und damit vielen verschiednen Text-Editoren - eine Herausforderung.
Auch die Substitution von Textelementen klappt nicht in allen Fällen. Probleme gibt es manchmal bei den sogenannten literal blocks, also Textblöcke, deren Inhalt ohne Formatierung konvertiert werden soll. Auch, was die Zeilenlänge angeht, sollte man die Ausgabe dieser Literal Blocks genau prüfen, da die Konvertierung zu lange Zeilen unter Umständen einfach abschneidet. Bei Code-Listings oder Kommandozeilenbeispielen sorgt das für Verwirrung beim Leser. Schließlich ist die Erzeugung von Tabellen, die am Ende sowohl in HTML und PDF schön aussehen, eine Herausforderung, die mit viel Versuch und Irrtum verbunden ist.
Der Autor findet: Die Gesamtzahl der Vorzüge macht diese Unannehmlichkeiten allemal wett.
Autoreninformation
Lenz Grimmer ist bei der SUSE LINUX GmbH für die Weiterentwicklung des quelloffenen Storage-Managementsystems openATTIC verantwortlich. Er befasst sich seit seinem Informatikstudium in den 1990er Jahren privat und beruflich mit Linux und Open-Source-Software. Häufig ist er auf Veranstaltungen anzutreffen, wo er Vorträge zu den unterschiedlichsten OSS-Technologien hält (zum Beispiel Storage und Infrastruktur). Sein privates Blog und weitere Links sind unter http://blog.lenzg.net/ zu finden.
Dieser Artikel ist zuerst erschienen in UpTimes, Mitgliederzeitschrift des GUUG e.V., Ausgabe 2016-2. Veröffentlichung mit freundlicher Genehmigung.
