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
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
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" ]
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'
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
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.
War dieser Beitrag hilfreich?
Weitere Beiträge
von Daniel Kocot
20.11.2024 Dein Job bei codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
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.
Blog-Autor*in
Daniel Kocot
Senior Solution Architect / Head of API Consulting
Du hast noch Fragen zu diesem Thema? Dann sprich mich einfach an.
Du hast noch Fragen zu diesem Thema? Dann sprich mich einfach an.