//

Getting project documentation done with Azure DevOps – Diagrams with PlantUML

22.12.2021 | 4 minutes of reading time

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
14

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
34

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" ]
14

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'
26

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
30

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.

share post

Likes

0

//

More articles in this subject area\n

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.