© StonePictures/Shutterstock.com
Kolumne: Hitchhiker’s Guide to Docs as Code

Kolumne: Hitchhiker’s Guide to Docs as Code


Wenn es um die Modellierung von Architekturen geht, also das 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 [1] 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.

Listing 1: Ein einfacher selbsterstellter Task

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 [2] (kurz GDK) voll zum Einsatz: Datei mit new File() anlegen und per .write() schreiben. Um alles andere, inklusive des Schließens 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 [3] 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 Architekturmo...

Exklusives Abo-Special

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang