Kolumne

Hitchhiker’s Guide to Docs as Code: Tools für AsciiDoc/Asciidoctor

Gernot Starke, Ralf D. Müller

Eine Internetsuche nach den Stichworten „Asciidoc Tool“ liefert fürchterlich viele Treffer. Wir möchten den Dschungel der Möglichkeiten etwas lichten und Ihnen einige der weiter verbreiteten Werkzeuge kurz vorstellen. Dabei gehen wir vom konkreten Bedarf aus und möchten Tools vorstellen, die den Docs-as-Code-Ansatz konkret unterstützen.

Im Verlauf des Artikels sehen wir uns auch verschiedene Kategorien jener Werkzeuge an (Abb. 1), die den Ansatz „Docs-as-Code“ unterstützen. Dazu gehören Editoren, um AsciiDoc-Texte zu erstellen und zu pflegen. Wir wissen, dass wir uns damit aufs Glatteis begeben – etwa genauso wie bei der Diskussion, ob „Tabs oder Spaces“ – denn insbesondere für Editoren werden Sie sicherlich starke persönliche Vorlieben haben. Aber halb so wild, vermutlich gibt es auch für Ihren Lieblingseditor oder Ihre Lieblingsentwicklungsumgebung mittlerweile Plug-ins, Bundles oder Add-ons, die AsciiDoc unterstützen.

Abb. 1: Übersicht der Tools

Gemeinsam mit den Editoren diskutieren wir Preview- oder WYSIWYG-Tools, die Ihnen bereits während des Schreibens eine Vorschau des Dokuments (üblicherweise in HTML) liefern. Anschließend werfen wir einen Blick auf Werkzeuge, um AsciiDoc-Texte in andere Formate zu übersetzen, sogenannte Prozessoren, und Werkzeuge, um die für Docs as Code notwendigen Prozesse zu automatisieren. Hier befassen wir uns kurz damit, wie klassische Build-Werkzeuge AsciiDoc unterstützen. Schließlich thematisieren wir auch sonstige Werkzeuge rund um AsciiDoc (etwa um Javadoc-Kommentare in AsciiDoc-Syntax schreiben zu können, Tools zur Prüfung der generierten Artefakte, Tools, um Websites mit AsciiDoc zu erstellen und zu pflegen etc.).

Lassen Sie uns mit den Editoren beginnen: Als ersten Kandidat möchten wir einen speziell für AsciiDoc entwickeltes Exemplar vorstellen, das ein kleines Team Softwerker als Open-Source-Projekt implementiert, weil sie damit Bücher schreiben wollten (bzw. auch geschrieben haben). Wie immer finden Sie den Quellcode dieser Kolumne online hier.

AsciidocFX

Als Open-Source-Projekt hat AsciidocFX im Jahr 2015 sogar einen Duke‘s Choice Award gewonnen – sicherlich berechtigte Lorbeeren. Wie der Name schon andeutet, ist AsciidocFX in Java geschrieben und verwendet JavaFX als UI-Technologie. Installer sind mit und ohne JRE für die gängigen Plattformen verfügbar. Er bietet eine Live-Preview, Integration von PlantUML und diversen anderen Grafik-Add-ons. Abbildung 2 verschafft einen ersten Eindruck. Obwohl uns sowohl Funktionsumfang, Stabilität wie auch Support seitens der Entwickler überzeugen, sind wir mit AsciidocFX niemals so richtig warm geworden, beim Schreiben zog es uns immer wieder zu unseren „normalen“ Editoren zurück, die neben AsciiDoc die für Entwickler notwendigen anderen Dinge verstehen.

Abb. 2: AsciidocFX

Dennoch bringt AsciidocFX ein paar Besonderheiten mit, die einem den Einstieg in das Schreiben mit AsciiDoc erleichtern können. Dieser Editor verfügt über eine klassische Iconleiste für Formatierungen. Benutzt man sie, werden die entsprechenden Textschnipsel eingefügt. Das kann vor allem bei selten genutzten Features wie Tabellen den Blick in die Dokumentation ersparen. Auch die Möglichkeit, direkt aus dem Editor heraus ein PDF oder E-Book zu erzeugen, ist einzigartig.

Atom

Gesponsert durch GitHub entstand vor einigen Jahren der Atom-Editor, mit dem Ziel, ein „anpassbarer Editor fürs 21. Jahrhundert“ zu werden (Abb. 1). Vollständig basierend auf Webtechnologien mit zahlreichen (freien) Erweiterungen hat Atom seine früheren Kinderkrankheiten, insbesondere die Performanceprobleme bei größeren Dateien, heute hinter sich gelassen. Atom läuft auf allen gängigen Betriebssystemen, mittlerweile unterstützt er sogar kollaboratives Editieren: Mehrere Personen an verschiedenen Orten bearbeiten dasselbe Dokument – wirklich cool! Zu Atom gibt es einen aus unserer Sicht hörenswerten Podcast mit Nathan Sobo, der die Idee zu Atom hatte und von dem auch ein erheblicher Teil des Quellcodes stammt.

Für AsciiDoc gibt es im Atom-Universum recht breite Unterstützung: Neben dem Syntax-Highlighting hat Atom insbesondere eine Preview, die auch geschachtelte Includes sowie Bilder versteht. Wie auch (fast) alle anderen Preview-Funktionen scheitert Atom jedoch an der Vorschau von PlantUML-Diagrammen, die im Quelltext innerhalb der AsciiDoc-Dokumente eingebettet sind (das oben genannte AsciidocFX bildet hier eine löbliche Ausnahme). Allerdings existiert für Atom auch ein PlantUML-Plug-in, mit dessen Hilfe sich fast interaktiv PlantUML-Diagramme erstellen und dann per include in AsciiDoc integrieren lassen. Aus unserer Sicht ist das an WYSIWYG-Unterstützung völlig ausreichend.

VS Code

Erich Gamma ist sicherlich vielen als einer der Autoren des berühmten Gang-of-Four-Buchs zu Entwurfsmustern bekannt. Andere kennen ihn als einen der ursprünglichen Väter von Eclipse. Ach ja, mit Kent Beck hat er auch JUnit erfunden. Inzwischen baut er im Auftrag von Microsoft an einer modernen plattformübergreifenden, erweiterbaren Entwicklungsumgebung für Web- und Cloud-Anwendungen namens Visual Studio Code (VS Code) (Abb. 1). Im Gegensatz zu seinen großen (kommerziellen) Windows-only-Geschwistern der Visual-Studio-Reihe kommt VS Code als Multiplattformleichtgewicht daher. VS Code bietet mittlerweile ein riesiges Portfolio an Plug-ins für die meisten gängigen Sprachen und ist im Gegensatz zu Atom, Sublime und Co. eben eine Entwicklungsumgebung mit Debugger. Das braucht der Entwickler vielleicht selten, aber wenn, ist dieses Feature Gold wert.

Für AsciiDoc gibt es natürlich auch ein Plug-in, das allerdings eine Installation des Asciidoctor-Prozessors voraussetzt. Unter Mac und Linux mittels gem install asciidoctor fast ein Kinderspiel, Windows-User müssen etwas tiefer in die Installationstrickkiste greifen, was abschrecken könnte. Wir finden allerdings, die Mühe lohnt, denn VS Code geht über reine Editorfunktionen hinaus.

Onlineeditor und reine Previews

Wer AsciiDoc ausprobieren oder demonstrieren möchte, ohne gleich etwas zu installieren, verwendet einfach AsciiDocLIVE, einen webbasierten AsciiDoc-Editor (Abb. 3). Für diverse Browser ist auch ein passendes AsciiDoc-Add-on verfügbar, das AsciiDoc-Dateien on the fly in HTML übersetzt und anzeigt. On the fly bedeutet dabei, dass eine in den Browser geladene AsciiDoc-Datei per JavaScript zur Anzeige nach HTML gewandelt wird. Diesen Ansatz finden wir nur in den wenigen Fällen hilfreich, in denen gerade kein Editor mit echter Preview zur Hand ist, im täglichen Leben nutzen wir es nur selten. Durch etwas Build-Magie lässt sich ein Browser auch in eine vollständige Preview-Ansicht mit Live-Reload verwandeln.

Abb. 3: AsciiDocLIVE

Schwenken wir zur nächsten Kategorie von Tools: den „echten“ Entwicklungsumgebungen. Damit kommen Docs noch näher an Code als bei reinen Editoren: Wer Quellcode und Dokumentation in derselben Entwicklungsumgebung bearbeitet, spart sich nervige Werkzeug- oder Paradigmenwechsel.

IntelliJ

Vermutlich müssen wir an dieser Stelle über IntelliJ (Abb. 1) nichts mehr schreiben und können direkt auf den AsciiDoc-Support eingehen. Die Preview versteht geschachtelte Includes und Bilder, ist robust und erlaubt flüssiges Arbeiten. Falls Sie mit IntelliJ Software entwickeln, sollten Sie die AsciiDoc-Plug-ins auf jeden Fall installieren. Das arc42-Template, das ja seit Version 7 komplett auf AsciiDoc-Basis gepflegt wird, ist zum größten Teil mithilfe von IntelliJ geschrieben worden.

Eclipse

Der AsciiDoc-Support von Eclipse (Abb. 1) liegt (zumindest bis Februar 2018) deutlich hinter den Möglichkeiten von IntelliJ zurück. Das bei Eclipse in der Java-IDE standardmäßig mitgelieferte MyLyn-Plug-in versteht die Grundzüge von AsciiDoc und enthält eine (leider sehr rudimentäre) Preview-Funktion. Mit dem (zumindest unter macOS) fehlenden Syntax-Highlighting und der nur rudimentären Preview (kein Zoom, nicht in eigenem Fenster darstellbar) können wir gut leben, aber Tabellen haben für uns nicht funktioniert. Das schränkt den Einsatz für Architekturdokumentation mit arc42 sehr ein.

Eclipse versteht aktuell auch keine include-Statements in AsciiDoc-Dateien – ein klares No-Go aus unserer Sicht. Ähnliches müssen wir zum eingeschränkten AsciiDoc-Support in NetBeans sagen. Für Eclipse- oder NetBeans-Nutzer käme daher eines der oben genannten Browser-Preview-Plug-ins zum Zuge.

AsciiDoc-Prozessoren

Als Prozessoren bezeichnen wir hier Werkzeuge, die AsciiDoc-Dokumente in HTML5 oder andere Formate konvertieren können. In dieser Kategorie finden sich drei wesentliche Vertreter. AsciiDoc war die ursprüngliche Referenzimplementierung (in Python) von Stuart Rackham, die es seit ca. 2002 gibt. Er hat auch die erste Syntaxdefinition geschaffen. AsciiDoctor ist eine vollständige Neuimplementierung in Ruby, die (im Gegensatz zur früheren Python-Version) signifikant auf Performance, Modularisierung und Erweiterbarkeit Wert legt. Sie wird maßgeblich von Dan Allen gepflegt (Twitter: @mojavelinux). AsciidoctorJ ist der JRuby-Wrapper, der es ermöglicht, Asciidoctor auf der JVM auszuführen. Asciidoctor.js ist eine JavaScript-Version von Asciidoctor, die über Opal-Source-2-Source-Compiler von Ruby in JavaScript übersetzt wird. Diese Portierung ist Grundlage für die In-Browser-Live-Preview-Add-ons.

Mit diesen Prozessoren haben Sie vermutlich nur in Ausnahmefällen direkt zu tun – üblicherweise verbergen Sie die notwendigen Parameter und Aufrufdetails besser hinter dem Build-Werkzeug Ihrer Wahl, beispielsweise Maven, Gradle oder unseretwegen auch dem Klassiker make.

Lesen Sie auch: Hitchhiker’s Guide to Docs as Code: The Beautiful Code

Build-Werkzeuge

In den letzten Folgen haben wir stets Gradle als das Docs-as-Code-Build-Werkzeug verwendet. Unter anderem haben wir Gradle wegen der Option, Groovy-Code innerhalb von Build-Skripten verwenden zu können, aber auch aufgrund der Einfachheit der AsciiDoc-Integration, benutzt. Nun möchten wir der Vollständigkeit halber auch Maven als verbreitetes Build-Werkzeug auf seine Tauglichkeit bezüglich Docs as Code respektive AsciiDoc untersuchen.

Unter pflegt das Asciidoctor-Team ein Repository mit vielen Maven-Beispielen. Dort können Sie sehen, wie der elegante Gradle-Einzeiler mit Maven deutlich mehr Umfang zulegt.

Hervorheben möchten wir die Unterstützung für Maven Site, das Kommando, das mehrere Aspekte eines Projekts übersichtlich als HTML dokumentiert.

Eingangs hatten wir auch make erwähnt: Wir raten zu moderneren Build-Tools, aber wenn Sie unbedingt wollen, finden Sie ein Makefile, mit dessen Hilfe Sie Ihre AsciiDoc-Quelltexte in diverse Zielformate übersetzen können.

Fazit

Sie können AsciiDoc problemlos mit dem Editor Ihrer Wahl schreiben, wobei wir persönlich zu unseren Entwicklungsumgebungen tendieren. Die für AsciiDoc verfügbaren Plug-ins für IntelliJ, Atom oder VS Code haben uns auch im (teilweise harten) Praxiseinsatz überzeugt.

In der nächsten Folge betreiben wir (ausnahmsweise legales) Doping. Wir reizen unser favorisiertes Build-Werkzeug Gradle in Richtung Docs as Code so richtig aus. Bis dahin – happy Docu-Coding.

Geschrieben von
Gernot Starke
Gernot Starke
    Informatikstudium an der RWTH Aachen, Dissertation über Software-Engineering an der J. Kepler Universität Linz. Langjährige Tätigkeit bei mehreren Software- und Beratungsunternehmen als Softwareentwickler, -architekt und technischer Projektleiter. 1996 Mitgründer und technischer Direktor des „Object Reality Center“, einer Kooperation mit Sun Microsystems. Dort Entwickler und technischer Leiter des ersten offizielle Java-Projekts von Sun in Deutschland. Seit 2011 Fellow der innoQ GmbH.  
Ralf D. Müller
Ralf D. Müller
Ralf D. Müller arbeitet als Architekt und Entwickler. Er erlebt täglich die Notwendigkeit effektiver Dokumentation. Außerdem ist er erklärter AsciiDoc-Fan und Committer bei arc42 sowie Gründer des docToolchain-Projekts.
Kommentare

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.