Der Asciidoctor macht Hausbesuche

Neuigkeiten von der Insel  –  38 Kommentare

Dokumentation ist nicht gerade das Lieblingskind der Entwickler. Vordringlich Open-Source-Projekte leiden vielfach unter schwacher und nicht anwendungsgerechter Dokumentation, aber auch kommerzielle Software kann sich da nicht ausnehmen. Das wurde bei Red Hat schon lange erkannt, und aus dem Hause kommen einige Ideen zur vereinfachten Dokumentation von Projekten. Das JBoss-Test-Audit-Projekt ist nur eine davon. Im Umfeld der Integrations-Test-Suite Arquillian wurde viel mit Awestruct gearbeitet, um Anwender-Dokumentation aus unterschiedlichen Formaten zu generieren. Und auch Verlage wie O'Reilly setzen mit Systemen wie Atlas auf einen entwicklungsnahen Dokumentationsansatz.

Gemeinsam ist allen Ansätzen, dass die Dokumentation sich einfach erstellen lässt und somit kein zusätzlicher Aufwand beim Schreiben oder der Veröffentlichung entsteht. Das gehasste Textverarbeitungsprogramm Word kommt dabei also keinesfalls zum Einsatz. Grundlage ist bei allen Ansätzen eine einfache Seitenbeschreibungssprache. Vielfach kommen Haml, Markdown oder YAML zum Einsatz. Github verwendet für Nachrichten, Issues (Probleme) und Kommentare eine erweiterte Version von Markdown mit dem Kürzel GFM.

Eine Auszeichnungssprache hab ich bisher vergessen – das AsciiDoc-Format. Das bereits 2002 in Python geschriebene Projekt bringt zweierlei: eine Auszeichnungssprache und einen Ansatz zum Umwandeln dieser Sprache in diverse andere Formate wie HTML, PDF, EPUB oder auch Man-Pages. Dieser Ansatz ist schon recht lange auf dem Markt, hat aber aufgrund der gewählten Implementierung nicht viel Verbreitung in der Java-Welt gefunden. Vor gut einem Jahr (erster Commit am 01.06.2012) haben Ryan Waldron von GitHub (@erebor) und Dan Allen von Red Hat (@mojavelinux) eine Ruby-Portierung mit dem Namen Asciidoctor ins Leben gerufen – natürlich mit dem Ziel, es besser zu machen. Und das ist ziemlich gut gelungen, wie ein direkter Vergleich der Funktionen zeigt.

Erst kürzlich ist die Version 0.1.4 erschienen. Rund vier Monate nach dem letzten Release sind gut 90 Fehlerbehebungen und Erweiterungen in das Produkt geflossen. Eine 15-prozentige Geschwindigkeitssteigerung führt dazu, dass ein 16.000-Zeilen-Buch damit in weniger als 0,85 Sekunden zu HTML gerendert werden kann. Ganz nebenbei wurden viele Open-Source-Projekte auf das Format und den Publikationsprozess umgestellt. Darunter alte Bekannte wie Groovy, Spring XD, Spring Security, OpenShift Origin, Neo4j, CRaSH und RichFaces.

Ein umfangreiches Nutzerhandbuch steht nun auch bereit und erleichtert den Einstieg. Schon länger ist auch die Java-Integration für Asciidoctor zu haben. Mit ihr können AsciiDoc-Dokumente direkt in Java gerendert werden. Damit war der Weg zu einer Javadoc-Adaption nicht weit. Mit asciidoclet können Javadoc-Kommentare jetzt auch in AsciiDoc geschrieben werden. Und natürlich sind auch entsprechende Maven- und Gradle-Plug-ins vorhanden.

Wer schnell einmal probieren möchte, wie einfach es ist, ein entsprechendes AsciiDoc-Dokument mit Asciidoctor zu konvertieren, der kann einfach die folgende pom.xml verwenden:

 <build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor.version}</version>
<configuration>
<backend>html</backend>
</configuration>
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>

Jetzt noch eine Datei mit der Endung .adoc oder .asciidoc in das Verzeichnis src\main\asciidoc, und schon kann es losgehen. Unter target\generated-docs landet die erstellte HTML-Datei. Die Arbeit mit Templates und Bildern ist möglich, muss aber von Hand erledigt werden. Ein wenig mehr Komfort bietet hier Awestruct.

Mit diesen Werkzeugen bleibt keine Ausrede mehr: Gute Dokumentation lässt sich einfach und schnell erstellen. Happy documenting!