In our projects we rely on documentation, even if many people still assume that because of the Agile Manifesto documentation is no longer needed ;).
As far as tooling (in terms of documentation) is concerned, we very often use Confluence in projects. This tool provides a lot of possibilities for integration into the documentation process due to a large number of plugins. Whereby a wiki is actually always the last step in a documentation chain, since it is in the classic sense a knowledge base and not a real project-related living documentation. In recent years, the “docs-as-code” movement has become more and more popular. This is about keeping documentation close to the development sources and making it available based on lightweight markup languages, such as Markdown and Asciidoc(tor) . And it is precisely this “docs-as-code” that is also increasingly becoming part of products and platforms such as Gitlab and Azure DevOps. Azure DevOps even takes a new approach here. A wiki is provided on the basis of a Git repository. The content can be created using Markdown. With this wiki, we now have a first possibility to establish “docs-as-code” in a project. Azure goes a small step further and extends “docs-as-code” with the integrated Mermaid by “diagrams-as-code”.
With “diagrams-as-code”, we are enabled to create diagrams within a repository and have them versioned with the help of a DSL.
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
Well, that is good so far. Unfortunately, Microsoft has not managed to update to the latest version of Mermaid for almost two years (Developer Community ). So we can’t use the latest features of Mermaid, we only have the option of flowcharts, sequence charts or gant charts to choose from.
PlantUML
Since I regularly work with entity-relationship models in my current project and usually rely on PlantUML for the representation, I wanted to use this again.
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
Unfortunately, a direct integration into the Azure DevOps Wiki is currently not planned for PlantUML. We now need to find a solution that helps us to fully comply with the “docs-as-code” approach. Since “docs-as-code” is basically based on a pipeline, we will try to generate the graphics and diagrams in exactly this way. Since PlantUML is delivered as a JAR, we need to provide a corresponding runtime environment for the pipeline. This is done in the form of a Docker image which we then make available as a container within the pipeline. You can find the corresponding image in the Docker Hub . In the Git repo you can also find the following Dockerfile, which is the basis of the image:
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
Now we can create a repository in Azure DevOps that will contain the sources for graphics and diagrams. In this repository, there must be a plantuml folder. Now we need to create a pipeline for this repo, which basically converts all .puml files in the plantuml folder to PNG format on pushes to the repo. Subsequently, after moving the PNG files to a default build directory, they are published as an artifact using the UniversalPackages task as a package. In Azure DevOps, artifacts can be reused inside and outside projects by using a package feed.
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: '<NameofAzureDevOpsProject>/PlantUML-Images' 24 vstsFeedPackagePublish: 'plantuml-images' 25 packagePublishDescription: 'PlantUML Images'
At this point, we can use the feed to check in the automated PNG files to the wiki repository via git.
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
A new branch plantuml-images is being created by the push. Subsequently, this must be merged with the main branch via a pull request. This allows us to include the PNG files within the wiki supported by the Azure DevOps API (https://dev.azure.com///_apis/git/repositories//items?path=/plantuml-images/.png) and the img HTML tag.
Conclusion
This blog post describes a way to integrate PlantUML with the Azure DevOps Wiki. Even though the integration requires a lot of knowledge about Azure DevOps, it is still a very simple solution, but can also be extended in terms of linking build pipelines.
Was this post helpful?
More articles
fromDaniel Kocot
20.3.2024 Your job at codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
More articles in this subject area
Discover exciting further topics and let the codecentric world inspire you.
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 author
Daniel Kocot
Senior Solution Architect / Head of API Consulting
Do you still have questions? Just send me a message.
Do you still have questions? Just send me a message.