//

Projektdokumentation mit Azure DevOps – Diagramme

22.12.2021 | 4 Minuten Lesezeit

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

1sequenceDiagram
2    loop Daily query
3        Alice->>Bob: Hello Bob, how are you?
4        alt is sick
5            Bob->>Alice: Not so good :(
6        else is well
7            Bob->>Alice: Feeling fresh like a daisy
8        end
9
10        opt Extra response
11            Bob->>Alice: Thanks for asking
12        end
13    end
14

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.

1@startuml
2
3' hide the spot
4hide circle
5
6' avoid problems with angled crows feet
7skinparam linetype ortho
8
9entity "Entity01" as e01 {
10  *e1_id : number <<generated>>
11  --
12  *name : text
13  description : text
14}
15
16entity "Entity02" as e02 {
17  *e2_id : number <<generated>>
18  --
19  *e1_id : number <<FK>>
20  other_details : text
21}
22
23entity "Entity03" as e03 {
24  *e3_id : number <<generated>>
25  --
26  e1_id : number <<FK>>
27  other_details : text
28}
29
30e01 ||..o{ e02
31e01 |o..o{ e03
32
33@enduml
34

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:

1FROM docker.io/alpine:3
2LABEL maintainer="Daniel Kocot <daniel.kocot@codecentric.de>" \
3      description="Internal Docker image for PlantUML"
4
5ENV PLANTUML_VERSION 1.2021.16
6
7RUN apk update
8RUN apk add --no-cache graphviz openjdk8-jre curl ttf-droid
9RUN mkdir /app
10RUN curl -L https://sourceforge.net/projects/plantuml/files/plantuml.${PLANTUML_VERSION}.jar/download -o /app/plantuml.jar
11RUN apk del curl
12
13ENTRYPOINT [ "java", "-jar", "/app/plantuml.jar" ]
14

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.

1trigger:
2- main
3
4pool:
5  vmImage: ubuntu-latest
6
7steps:
8- script: docker run -v $(Build.Repository.LocalPath)/plantuml:/plantuml --rm -i codecentric/plantuml-docker:1.2021.16 plantuml/*.puml -w /plantuml -o ./output
9  displayName: Export PlantUML diagrams
10
11- task: CopyFiles@2
12  displayName: 'Copy generated PNGs by PlantUML'
13  inputs:
14    SourceFolder: './plantuml/output'
15    Contents: '*.png'
16    TargetFolder: '$(Build.ArtifactStagingDirectory)'
17 
18- task: UniversalPackages@0
19  displayName: 'Publish PlantUML images'
20  inputs:
21    command: publish
22    publishDirectory: '$(Build.ArtifactStagingDirectory)'
23    vstsFeedPublish: 'APIEnablement/PlantUML-Images'
24    vstsFeedPackagePublish: 'plantuml-images'
25    packagePublishDescription: 'PlantUML Images'
26

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

1pool:
2  vmImage: ubuntu-latest
3 
4steps:
5- checkout: self
6  persistCredentials: true
7 
8- task: CmdLine@2
9  inputs:
10    script:   git switch -c plantuml-images
11- task: UniversalPackages@0
12  displayName: 'Download PlantUML images'
13  inputs:
14    command: download
15    downloadDirectory: '$(Build.SourcesDirectory)/plantuml-images'
16    vstsFeed: '<NameofAzureDevOpsProject>/PlantUML-Images'
17    vstsFeedPackage: 'plantuml-images'
18    vstsPackageVersion: '*'
19 
20- task: CmdLine@2
21  inputs:
22    script: |
23      git config --global user.email <user.email>
24      git config --global user.name "<user.name>"
25      git pull
26      git add .
27      git commit -m "added PNGs generated by PlantUML"
28      git push --set-upstream origin plantuml-images
29  displayName: Adding PNGs by using GIT
30

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.

Beitrag teilen

Gefällt mir

0

//

Weitere Artikel in diesem Themenbereich

Entdecke spannende weiterführende Themen und lass dich von der codecentric Welt inspirieren.

//

Gemeinsam bessere Projekte umsetzen

Wir helfen Deinem Unternehmen

Du stehst vor einer großen IT-Herausforderung? Wir sorgen für eine maßgeschneiderte Unterstützung. Informiere dich jetzt.

Hilf uns, noch besser zu werden.

Wir sind immer auf der Suche nach neuen Talenten. Auch für dich ist die passende Stelle dabei.