Projektdokumentation mit Azure DevOps – Diagramme

In unseren Projekten sind wir auf Dokumentation angewiesen, auch wenn immer noch viele Menschen, von der Annahme ausgehen, dass aufgrund des Agilen Manifests keine Dokumentation mehr benötigt wird ;). Was das Tooling in Sachen Dokumentation angeht, treffen wir in Projekten sehr häufig auf Confluence. Dieses System liefert aufgrund einer Vielzahl von Plugins sehr viele Möglichkeiten einer Integration in den Dokumentationsprozess. Wobei ein Wiki eigentlich immer den letzten Schritt in einer Dokumentationskette darstellt, da es sich im klassischen Sinne um einen Wissensspeicher handelt und nicht um wirkliche projektbezogene lebende Dokumentation. In den letzten Jahren ist immer mehr die „docs-as-code“-Bewegung in Erscheinung getreten. Hierbei geht es darum, Dokumentation nah in den Entwicklungsquellen zu halten und diese auf Basis von leichtgewichtigen Markup-Sprachen, wie Markdown und Asciidoc(tor) , zur Verfügung zu stellen. Und genau dieses „docs-as-code“ wird auch immer mehr Teil von Produkten und Plattformen wie Gitlab und Azure DevOps. Azure DevOps geht hier sogar einen neuen Weg. Auf Basis eines Git-Repositories wird ein Wiki bereitgestellt. Die Inhalte lassen sich mittels Markdown erstellen. Mit diesem Wiki haben wir für uns nun eine erste Möglichkeit um „docs-as-code“ in einem Projekt zu etablieren. Azure geht noch einen kleinen Schritt weiter und erweitert „docs-as-code“ mit dem integrierten Mermaid um „diagrams-as-code“. Bei „diagrams-as-code“ werden wir mit Hilfe einer DSL in die Lage versetzt Diagramme, innerhalb eines Repositories und somit versioniert, zu erstellen.

Mermaid

Soweit so gut. Leider schafft es Microsoft seit fast zwei Jahren nicht auf die aktuellste Version von Mermaid zu aktualisieren (Developer-Community ). Somit können wir nicht die aktuellsten Features von Mermaid benutzen, sondern haben nur die Möglichkeit Flowcharts, Sequenzdiagramme oder Gant-Charts zur Auswahl.

PlantUML

Da ich in meinem aktuellen Projekt sehr viel mit Entity-Relationship Modellen arbeite und für die Darstellung in der Regel auf PlantUML setze, wollte ich dies auch gerne wieder verwenden.

Leider ist eine direkte Integration in das Azure DevOps Wiki aktuell für PlantUML nicht vorgesehen. Hier gilt es nun eine Lösung zu finden, die uns hilft dem Ansatz von „docs-as-code“ in Gänze gerecht zu werden. Da „docs-as-code“ grundsätzlich auf Basis einer Pipeline entstehen, werden wir versuchen die Grafiken und Diagramme auf genau dieser Basis zu generieren. Da PlantUML als JAR ausgeliefert wird, müssen wir für die Pipeline eine entsprechende Laufzeitumgebung zur Verfügung stellen. Dies geschieht in Form eines Docker-Image. Welches wir dann innerhalb der Pipeline als Container zur Verfügung stellen. Das entsprechende Image findet Ihr im Docker Hub . Im Git Repo findet Ihr auch das folgende Dockerfile, welches die Grundlage des Image ist:

Azure DevOps

Nun können wir in Azure DevOps ein Repository, indem die Sourcen für Grafiken und Diagramme enthalten sein sollen, erstellen. In diesem Repo muss ein Ordner plantuml vorhanden sein. Nun gilt es eine Pipeline für dieses Repo zu erstellen, die bei Pushes in das Repo grundsätzlich alle .puml-Dateien im Ordner plantuml in das PNG-Format konvertiert. Im Anschluss werden die PNG-Dateien, nachdem diese in ein Standardverzeichnis für den Build verschoben wurden, als Artefakt mit Hilfe des UniversalPackages-Task als Package veröffentlicht. In Azure DevOps lassen sich Artefakte durch die Verwendung eines Package-Feeds inner- und auch außerhalb von Projekten wiederverwenden.

Nun können wir die automatisiert erstellten PNG-Dateien mittels des Feeds in das Wiki Repository per git einchecken.

Durch das Einchecken entsteht ein neuer Branch plantuml-images. Im Anschluss muss dieser per Pull-Request mit dem main-Branch gemerged werden. Dadurch können wir die PNG-Dateien innerhalb des Wiki unterstützt durch die Azure DevOps API (https://dev.azure.com///_apis/git/repositories//items?path=/plantuml-images/.png) und dem img-HTML-Tag einbinden.

Zusammenfassung

In diesem Blogpost haben wir nun einen Weg für eine Integration von PlantUML ins Azure DevOps Wiki gefunden. Auch wenn die Integration viel Wissen über Azure DevOps voraussetzt, ist es dennoch eine sehr einfache Lösung, die sich aber auch im Hinblick auf Verknüpfung von Build-Pipelines erweitern lässt.