Agile, oven-fresh documentation. Part 2: PlantUML with JBake

After looking at the configuration of JBake in the first part , I will now extend the scenario described in the previous post by adding PlantUML. PlantUML makes it possible to describe UML diagrams in simple textual notation.

@startuml start :Hello world; stop @enduml

First of all, we will integrate PlantUML into the existing Gradle build file. In order to do so, we need asciidoctorj-diagram as an external library for the build script. With the upcoming release of the Gradle plugin it is no longer necessary. The configuration of JBake needs to be adjusted so that the asciidoctorj-diagram library can be used. The asciidoctorj-diagram library now allows us to use PlantUML diagrams within the Asciidoctor document.

buildscript {
    repositories {
        mavenCentral()
        jcenter()
    }
 
    dependencies {
        classpath 'org.asciidoctor:asciidoctorj-diagram:1.5.4.1'
    }
}
 
plugins {
     id 'org.jbake.site' version '1.0.0'
}
 
group 'de.codecentric.dk.afgd'
version '1.0-SNAPSHOT'
 
apply plugin: 'groovy'
apply plugin: 'java'
 
sourceCompatibility = 1.8
 
repositories {
    mavenCentral()
    jcenter()
}
 
dependencies {
    compile 'org.codehaus.groovy:groovy-all:2.3.11'
    testCompile group: 'junit', name: 'junit', version: '4.12'
}
 
jbake {
    srcDirName = 'src/documentation'
    destDirName = 'documentation'
    configuration['asciidoctor.option.requires'] = "asciidoctor-diagram"
    configuration['asciidoctor.attributes'] = [
            "sourceDir=${projectDir}",
            "imagesDir=diagrams",
            "imagesoutdir=${bake.input}/assets/diagrams"
    ]
}

build.dependsOn bake

We now create a new file, architecture.adoc, within the content folder. The following code block shows the content of the file.

= Architecture documentation
Daniel Kocot
2017-11-20
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published

== First draft

[plantuml, "first_draft", "png"]
----
node "Confluence as content repository" as nodeconf
folder Intranet{
    together {
        node "WordPress Node 1" as nodeiwp1
        node "WordPress Node 2" as nodeiwp2
        node "WordPress Node 3" as nodeiwp3
        node "WordPress Node 4" as nodeiwp4
    }
}
folder Extranet{
    together {
        node "WordPress Node 1" as nodeewp1
        node "WordPress Node 2" as nodeewp2
        node "WordPress Node 3" as nodeewp3
        node "WordPress Node 4" as nodeewp4
    }
}
node "LoadBalancer / nginx Intranet" as lbinginx
node "LoadBalancer / nginx Extranet" as lbenginx
node "Content Delivery Network" as cdn
cloud "Intranet" as intranet
cloud "Extra/Internet" as internet
actor "Internal User" as internal
actor "External User" as external
nodeconf --> nodeiwp1
nodeconf --> nodeiwp2
nodeconf --> nodeiwp3
nodeconf --> nodeiwp4
nodeconf --> nodeewp1
nodeconf --> nodeewp2
nodeconf --> nodeewp3
nodeconf --> nodeewp4
nodeewp1 <--> lbenginx
nodeewp2 <--> lbenginx
nodeewp3 <--> lbenginx
nodeewp4 <--> lbenginx
nodeiwp1 <--> lbinginx
nodeiwp2 <--> lbinginx
nodeiwp3 <--> lbinginx
nodeiwp4 <--> lbinginx
cdn <--> nodeconf
cdn --> nodeewp1
cdn --> nodeewp2
cdn --> nodeewp3
cdn --> nodeewp4
cdn --> nodeiwp1
cdn --> nodeiwp2
cdn --> nodeiwp3
cdn --> nodeiwp4
lbinginx <--> intranet
lbenginx <--> internet
external <--> internet
internal <--> intranet
----

After writing the first draft of our architectural diagram into the document, there is still the question of how the text content is turned into a graphic.

For this purpose, when creating the entire documentation, the first thing we do is generate a picture – in our case a PNG file – via PlantUML. This picture is saved in the assets folder under the file name first-draft with the file extension .png. In a second step, JBake will then create the corresponding HTML file based on the Asciidoctor file.

The PlantUML integration enables us to also maintain the important architecture diagrams in close alignment with the source code.

In the third part of this series, we will take a look at test reports and their integration in JBake.

Check out the demo in my Git Repository: agile-fresh-baked-docs