Alles im Griff
Projektdokumentation mit reStructuredText und Sphinx
Dieser Artikel beschreibt häufige Missstände und Probleme bei der Dokumentation von Software-Projekten. Mit der textbasierten Markup-Sprache reStructuredtText und dem Open-Source-Tool Sphinx zeigt er einen Lösungsansatz auf.
Um Entwicklern und Projektmanagern die Dokumentation eines Software-Produkts so einfach wie möglich zu machen, ist es wichtig, so viele Hürden wie möglich aus dem Weg zu räumen. Das Erstellen und Aktualisieren der Dokumentation muss integraler Bestandteil des Workflows werden. Wenn möglich, erfolgt es darum unter Einsatz bereits bekannter Werkzeuge.
Dieser Artikel beschreibt häufige Missstände und Probleme bei der Dokumentation von Software-Projekten. Anschließend zeigt er unter Zuhilfenahme des Open-Source-Tools Sphinx und der textbasierten Markup-Sprache reStructuredtText einen Lösungsansatz auf.
Ausgangssituation: Verwaiste Office-Dokumente
Als Ausgangssituation findet man in vielerorts Szenarien wie das Folgende. Mitunter gibt es bereits eine „Projektdokumentation“. Aber sie besteht oft aus mehreren Word- oder Libre-Office-Dokumenten auf einem zentralen Fileserver, oder befindet sich als Asset in einem Dokumentenmanagementsystem. Solche Dokumente wurden häufig irgendwann mal angelegt, etwa, weil ein neu hinzugekommener Teamleiter den Auftrag erteilte, mal Licht ins Projekt-Dickicht zu bringen. Daraufhin goss jemand den zu diesem Zeitpunkt aktuellen Stand des Projekts in ein Dokument, vergaß es und fasste es nie wieder an. Dokumentation in dieser Form wird erfahrungsgemäß selten bis gar nicht mit der laufenden Entwicklung synchronisiert. Es mangelt zum Beispiel an Zugriffsberechtigungen, oder auch schlicht an der Kenntnis über die Existenz eines solchen Dokuments.
Neben der so entstehenden mangelnden Aktualität haben Office-Dokumente in einem zentralen Dateiarchiv aber noch weitere Nachteile. Office-Dokumente machen Teamarbeit schwer bis unmöglich, insbesondere wenn mehr als ein Autor zeitgleich Änderungen an der Dokumentation durchführen soll. Auch wenn die gängigen Office-Anwendungen rudimentäre Unterstützung für Versionierung und Konsolidierung von Inhalten bieten, ist die korrekte Benutzung dieser Funktionalität den meisten Anwendern nicht geläufig. Letztendlich ist es doch wieder die Aufgabe eines Einzelnen, die verschiedenen Änderungen und Versionen zusammenzufassen und den letzten Stand in das Archiv hochzuladen.
Das macht insbesondere die Durchführung von Detailverbesserungen so unattraktiv, weil sie so aufwändig sind, dass sie schlichtweg nicht vorgenommen werden.
Auch die Dokumentierung verschiedener Software-Versionen ist bei Einsatz von Office-Dokumenten eine Herausforderung, also die parallele Dokumentation eines Projekts, das zum Beispiel in einer Release- und einer Entwicklungsversion existiert. Nun müssen nicht nur die Änderungen verschiedener Autoren berücksichtigt werden, sondern auch noch die Frage, in welche Versionszugehörigkeit des Dokuments sie zu übernehmen sind.
Anforderungen an ein Dokumentationsmanagementsystem
Um diese Defizite und Herausforderungen zu meistern, sollte ein optimales Dokumentationssystem folgenden Anforderungen entsprechen.
Der Quellcode der Dokumentation sollte im Plaintext-Format vorliegen, also als reine Textdateien. Dadurch ist die größtmögliche Plattformunabhängigkeit gewährleistet, da die Bearbeitung nicht nur über ein einzelnes Tool oder auf einer bestimmten Plattform erfolgen muss. Der Entwickler kann stattdessen den Text-Editor seiner Wahl verwenden. Der Text lässt sich automatisiert mit gängigen Unix-Bordwerkzeugen wie grep, sed oder awk durchforsten und bearbeiten.
Reiner Text ermöglicht weiterhin eine einfachere Versionskontrolle und Kollaboration mit den vertrauten Entwicklerwerkzeugen und Methoden, also etwa Diffs, Branches und Merging. Damit ist die Dokumentation gefühlt näher am Code, was die Zugänglichkeit fördert. Es kommt also durch die Verwendung der gleichen Tools für Code-Entwicklung und Dokumentation zu keinem Medienbruch. Liegen Code und Dokumentation im gleichen Quelltext-Repository, lässt sich die Anpassung von Code inklusive der eventuell notwendigen Aktualisierung der Dokumentation im gleichen Commit einchecken. Das macht es deutlich einfacher, Code- und Doku-Änderungen im Nachhinein nachzuvollziehen.
Doch reiner Text allein reicht noch nicht aus. Notwendig ist auch eine Möglichkeit zur Formatierung und Strukturierung des Dokuments mit Hilfe textbasierter Markup-Elemente. Die Syntax sollte leicht zu erlernen sein, nicht zu sehr vom Inhalt ablenken und den Quelltext weiterhin lesbar erscheinen lassen. Hilfreich wäre auch die Unterstützung der Markup-Sprache durch den jeweiligen Text-Editor zum Beispiel durch Syntax-Highlighting, automatische Vervollständigung oder einfaches Anstoßen des Build-Prozesses.
Das Dokumentationsmanagementsystem sollte darüber hinaus automatisch verschiedene und möglichst plattformunabhängige Ausgabeformate generieren. Insbesondere sind hier PDF, HTML und ePub für E-Book-Reader zu nennen.
Idealerweise sollte die verwendete Software schließlich unter einer Open-Source-Lizenz verfügbar sein. Das bringt die bekannten Vorzüge mit sich: keine Lizenzgebühren, keine Abhängigkeit von einem bestimmten Hersteller, offene Formate, leichte Anpassbarkeit und Erweiterbarkeit.
