Agile, frisch gebackene Dokumentation – Teil 2: PlantUML mit JBake

Nachdem wir uns im ersten Teil mit der Konfiguration von JBake beschäftigt haben, möchte ich in diesem Blogpost das Szenario um PlantUML erweitern.
PlantUML ermöglicht es, UML-Diagramme in einfacher textueller Notation zu beschreiben.

@startuml start :Hello world; stop @enduml

Wir wollen nun PlantUML zu allererst in das bestehende Gradle Buildfile integrieren. Hierzu benötigen wir AsciidoctorJ-Diagram als externe Bibliothek für das Buildscript. Die Konfiguration von JBake muss für die Verwendung der asciidoctorj-diagram-Bibliothek angepasst werden. Die Bibliothek AsciidoctorJ-Diagram ermöglicht es nun, PlantUML-Diagramme innerhalb des Asciidoctor-Dokuments zu verwenden.

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

Nun erstellen wir innerhalb des content-Ordners eine neue Datei architecture.adoc. Der Inhalt der Datei kann dem nachfolgenden Code-Block entnommen werden.

= 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
----

Nachdem wir den ersten Draft für unser Architekturdiagramm in das Dokument geschrieben haben, bleibt nun die Frage, wie aus den Textinhalten nun eine Grafik wird.

Hierzu wird beim Erstellen der gesamten Dokumentation im ersten Schritt per PlantUML nun ein Bild, in unserem Fall im PNG-Format, generiert. Dieses wird im Assets-Ordner mit dem Namen first-draft und der Dateiendung .png gespeichert. In einem zweiten Schritt erstellt JBake nun die entsprechende HTML-Datei auf Basis der Asciidoctor-Datei.

Durch die Integration von PlantUML sind wir in die Lage versetzt, auch die wichtigen Architekturdiagramme nah am Quellcode zu pflegen. Im dritten Teil dieser Reihe werden wir einen Blick auf Testreports und deren Integration in JBake werfen.

Eine Demo findet ihr in meinem Git-Repository agile-fresh-baked-docs .