Kolumne

Hitchhiker’s Guide to Docs as Code: Diagramme, jetzt wird modelliert!

Gernot Starke, Ralf D. Müller

© SuS_Media

Wenn es um die Modellierung von Architekturen geht, also dem Erstellen eines Modells mit verschiedenen Sichten anstelle von unkorrelierten Zeichnungen, dann reicht das Einbinden von statischen Diagrammen oder PlantUML nicht mehr aus. Deshalb greifen wir in dieser Folge etwas tiefer in den Werkzeugkasten und integrieren echte Modelle in unseren Docs-as-Code-Ansatz.

Der Build kann mehr

Bislang wurden über den Build nur Plug-ins referenziert und deren Tasks gestartet. In Gradle kann ein Task aber ganze Skripte beherbergen und wird so zum mächtigen Werkzeug. Gradle unterstützt von Haus aus Java, Groovy und seit einiger Zeit auch Kotlin. Aufgrund der Nähe zu Java und der kompakteren Syntax bevorzugen wir für das Schreiben von Tasks Groovy. Groovy bringt gegenüber Java auch noch einige Abkürzungen mit. Listing 1 zeigt einen einfachen Task, der ein Changelog Ihrer Dokumentation erstellt.

task exportChangeLog {
  description 'exports the change log from a git subpath'
  doLast {
    def changes = "git log ./src/docs/arc42".execute().text
    def path = './build/docs/'
    new File(path).mkdirs()
    def changelog = new File(path + 'changelog.adoc')
    logger.info "> changelog exported"
    changelog.write(changes)
  }
}

Die erste Zeile des doLast-Blocks demonstriert gleich die Eleganz von Groovy. In einer Zeile wird ein Befehl auf der Kommandozeile mit .execute() ausgeführt, das Ergebnis per .text abgefangen und in eine Variable geschrieben. Wer noch nicht mit Groovy gearbeitet hat: Für Groovy ist .text das Gleiche wie .getText() – die Abkürzung macht den Code jedoch kompakter.

In diesem Beispiel wird das Ergebnis anschließend einfach in eine Datei geschrieben. Auch hier kommen die Abkürzungen des Groovy Developments Kits (kurz GDK) voll zum Einsatz: Datei mit new File() anlegen und per .write() schreiben. Um alles andere, inklusive dem Schließen der Datei, kümmert sich Groovy. Wenn Ihnen das zu viel Neues ist, nutzen Sie einfach Ihr Java-Wissen. Gefallen Ihnen aber diese Abkürzungen, dann ist die Liste der Unterschiede von Groovy zu Java mit Sicherheit ein guter Einstieg.

Aber was hat das jetzt mit Diagrammen zu tun? Unserer Ansicht nach eine Menge: Was beispielsweise an (normaler) Dokumentation nervt, sind diese lästigen manuellen Trivialitäten. Dazu gehört, erstellte Diagramme in die Dokumentation zu kopieren, zwischen Diagrammen und textueller Beschreibung zu springen und x-Diagramme zu aktualisieren, wenn sich im Architekturmodell auch nur der Name eines Architekturbausteins geändert hat.

Das Beispiel in Abbildung 1 zeigt einen Ausschnitt der Architektur von docToolchain (Kasten: „Was ist docToolchain?“) in Enterprise Architect, einem kommerziellen und recht verbreiteten Modellierungswerkzeug von Sparx Systems. Rechts oben finden Sie einen Kommentar zu einem der Modellierungselemente geöffnet. Unsere Anmerkungen gelten auch für viele andere Modellierungswerkzeuge, weil die meisten modernen Tools mittlerweile eine Schnittstelle zum Fernsteuern oder ein API zum direkten Datenzugriff anbieten. Genau dort setzen wir nun an.

Abb. 1: Beispiel für ein Architekturmodell

Export Automat

Mit einem eigens dafür geschriebenen Task in Ihrem Asciidoctor Gradle Build können Sie nun nach UML-Modellen in Ihrer Dokumentation suchen, diese im Build automatisiert öffnen, alle Diagramme automatisiert exportieren und alle Notizen hinter den Elementen exportieren. Der nächste aufzurufende Build-Task kann dann wie gehabt die exportierten Diagramme über eine Referenz und die exportierten Kommentare als Textmodule in Ihre Dokumentation einbinden und HTML oder PDF generieren. Kein Copy and Paste mehr, sondern automatische Aktualisierung Ihrer Dokumentation mit allen Diagrammen.

Die Verwendung des Sparx Enterprise Architect als UML-Modellierungstool ist nur als Beispiel gedacht. Die Idee der Automatisierung des Pflegeaufwands Ihrer Dokumentation steht im Vordergrund. Die zeitlichen Einsparungen bei der Pflege umfangreicherer Dokumentationen rechtfertigt es oftmals, die Entwicklertrickkiste zu öffnen und im Sinne der Continuous Documentation auch andere Schritte in Ihrer Dokumentationspipeline der Maschine zu überlassen.

Was ist docToolchain?
Beim Lesen unserer Kolumne ist Ihnen bestimmt schon aufgefallen, dass sich mit Asciidoctor viel erreichen lässt, man aber auch viel konfigurieren muss. Damit das alles richtig läuft und man z. B. auch immer die richtigen Versionen der Plug-ins zur Hauptversion des Asciidoctor-Gradle-Plug-ins erwischt etc., wäre es doch schön, wenn man einen vorkonfigurierten Build hätte, der alle von uns beschriebenen Features umsetzt. Genau das ist docToolchain – ein Open-Source-Projekt das Ihnen den Umgang mit dem Docs-as-Code-Ansatz erleichtert. Die in dieser Folge beschriebenen export-Tasks finden Sie auch einsatzbereit in diesem Projekt.

Hitchhikers Guide to Docs as Code

Mit ihrer Kolumne Hitchhikers Guide to Docs as Code – kurz HHGDC – möchten die beiden Autoren Gernot Starke (innoq) und Ralf D. Müller (freier Softwareentwickler) die Mühen der Dokumentation lindern. Ihr Ansatz ist es Softwaredokumentation wie Code zu behandeln: schreiben, bauen, testen, committen, mergen.

Polyglot

Zwar haben wir anfangs die Vorzüge von Groovy als Sprache für die Umsetzung des Gradle-Tasks angepriesen, dennoch ist es sinnvoll, die Werkzeuge passend zum Problem zu wählen. Bei der Automatisierung von Desktopanwendungen unter Windows sind das Visual Basic oder PowerShell. Windows-Anwendungen bringen zur Automatisierung meist COM-Schnittstellen mit, die sich auch in Java mit COM Bridges ansprechen lassen, die jedoch eine zusätzliche DLL erfordern.

Diese Abhängigkeit lässt sich umgehen, indem Sie, wie in Listing 1 gezeigt, aus Groovy ein Visual-Basic-Skript über die Shell starten. Da Enterprise Architect eben unter Windows läuft, haben wir hier kein schlechtes Gewissen gegenüber der *ix-Fraktion. Dieses Skript entwickeln Sie dann komfortabel zunächst in einer passenden IDE und kopieren es nach Fertigstellung in den Build. Somit müssen Sie auch nicht auf die Unterstützung der IDE bei COM-Objekten verzichten.

Da ein solcher Export etwas länger dauern kann, ist das in Listing 1 gezeigte Beispiel zur Ausführung eines Kommandos etwas zu trivial. docToolchain enthält deshalb eine Methode executeCMD, die per Metaprogrammierung der String-Klasse hinzugefügt wird. Beim Aufruf wartet diese Methode nicht das Ende des Kommandos ab, sondern gibt bereits während der Ausführung alle Programmausgaben aus. Sie können dem Export bei seiner Arbeit während des Builds zusehen. Listing 2 zeigt die Ausgabe unseres Beispielcodes, den wir wieder für Sie auf GitHub veröffentlicht haben.

PS C:\Users\javamagazin\folge-6> .\gradlew.bat exportEA

> Configure project :
compiling with Java 1.8.0_111 at 21:43:37
docDir: .
mainConfigFile: Config.groovy
inputPath: src/docs
inputFiles: [[file:demo.adoc, formats:[html, pdf, docbook]]]
outputPath: build/docs
./build/docs/ppt/images

Image extractor
looking for .eap files in folge-6\src
found folge-6\src\docs\Models.eap
opening Enterprise Architect. This might take a moment...
 extracted image to ./src/docs/images/ea/Manual/exportEA.png
 extracted image to ./src/docs/images/ea/Manual/Overview.png
 extracted image to ./src/docs/images/ea/Manual/arc42_asciidoc_template.png
finished exporting images

Wie schon genannt, geht es hier vor allem um die Idee der Automatisierung und nicht um eine konkret einzusetzende Software. Der Diagrammexport für Enterprise Architect war die erste Implementierung der Idee im docToolchain-Projekt. Wenn Sie lieber mit MS Visio modellieren, dann können Sie die Lösung von Frank Pohl einsetzen. Auch ein PowerPoint-Export ist implementiert und einsatzbereit. Sie benutzen ein anderes Tool? Mit den genannten Beispielen als Template wird es Ihnen gelingen, den Ansatz auch für Ihre Diagramme umzusetzen.

Windows, Linux und der Build-Server

Durch die Automatisierung von Windows-basierten Werkzeugen stellt sich nun die Frage, wie Sie weiter Ihre Dokumentation bei Änderungen auf dem Build-Server bauen können. Mit Wine und CrossOver können Sie einen solchen Export auch unter Linux oder macOS realisieren. Gehen Sie diesem Problem pragmatisch aus dem Weg: docToolchain exportiert die Diagramme und Notizen in das ./src– anstelle des ./build-Verzeichnisses und nimmt die Dateien in die Versionskontrolle mit auf.

Was auf den ersten Blick nach einem Best-Practice-Verstoß aussieht, entpuppt sich als praktisch. Sie führen den Export auf Ihrem lokalen System aus, anschließend kann Ihr Build-Server die Dokumentation in den verschiedenen Formaten bauen.

Zusätzlich sind Änderungen an den exportierten Elementen durch die Versionierung leichter als im meist binären Ursprungsformat zu verfolgen. Als dritten Vorteil erhalten Sie Unabhängigkeit vom proprietären Ausgangsformat. Ihre Dokumentation lebt ja vermutlich einige Jahre. Sollten Sie in dieser Zeit aus verschiedenen Gründen die Möglichkeit verlieren, das Ausgangsformat weiter zu pflegen, können Sie weiterhin auf die generierten Bilder und Texte zugreifen.

Fazit

In dieser Folge unserer Kolumne haben Sie gesehen, dass Sie (Groovy und Gradle sei Dank) ziemlich einfach weitere Werkzeuge in den Build integrieren und somit die Wartung und Pflege Ihrer Dokumentation stark vereinfachen können. Docs as Code hört nicht schon bei Versionierung und einfachen Konvertierung auf. In der nächsten Folge zeigen wir Ihnen dann, wie und warum Sie Sourcecode direkt aus Ihrer Dokumentation referenzieren sollten. Bis dahin wünschen wir fröhliche Automatisierung!

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

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
400
  Subscribe  
Benachrichtige mich zu: