Agile, frisch gebackene Dokumentation – Teil 1: JBake

2 Kommentare

In Softwareentwicklungsprojekten steht man immer wieder vor der Frage, wie denn das jeweilige Projekt in vollem Umfang dokumentiert werden könnte. In der Regel nimmt man meistens Confluence oder ein anderes Wiki zur Hand. Aber warum entwickeln wir die Dokumentation des Projekts nicht direkt am Code? Zu diesem Zweck möchte ich euch in diesem ersten Teil der Artikelserie JBake ein wenig näher bringen.
JBake ist eigentlich ein Generator für statische Webseiten. Dan Allen, Project Lead des Asciidoctor-Projekts, bezeichnet es als „Jekyll of the JVM“. Anhand von Plugins für Maven und Gradle lässt sich JBake auf relativ einfache Art und Weise in Build Pipelines integrieren.
Ich möchte nun anhand eines Beispiels die Einsatzmöglichkeiten von JBake erläutern. Zu allererst werden wir ein einfaches Gradle-Projekt bauen, um eine Ausgangsbasis für die weiteren Schritte zu schaffen.

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

Nun wird die Build-File um das Plugin jbake-gradle-plugin erweitert.

plugins {
     id 'org.jbake.site' version '1.0.0'
}

Dadurch erhalten wir nun einen weiteren Task „bake“, der es uns erlaubt, Dokumentation zu „backen“. Desweiteren benötigen wir hierzu noch eine JBake-Basisinstallation innerhalb der Sourcen. Unter dem MacOS-Betriebssystem lässt sich dies leicht mit SDKMAN (

$ sdk install jbake

) oder Homebrew (

$ brew install jbake

) erledigen.

Standardmäßig erwartet das Gradle-Plugin die Dokumentationsquellen unter src/jbake. Mit Parametern im Build-File lässt sich der Quell- und Zielort aber anpassen, wobei das Ziel immer im Build-Ordner liegt. In unserem Fall mit den folgenden Werten:

jbake {
     srcDirName = 'src/documentation'
     destDirName = 'documentation'
}

Da nun JBake installiert ist, kann im Verzeichnis

src/documentation

der Befehl

jbake -i

ausgeführt werden. Die so entstandene Struktur lässt sich nun nach Belieben erweitern und anpassen. Als Inhalt lassen sich im content-Ordner HTML-, Asciidoctor- oder Markdown-Dateien hinterlegen. Im Rahmen des Blogartikels wird die vorhandene Datei about.html durch about.adoc ersetzt und der Inhalt entsprechend angepasst.

= Project documentation
Daniel Kocot
2017-10-03
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published

Innerhalb des Asciidoctor-Dokuments können JBake-Metainformationen hinterlegt werden, wie Seitentyp, Tags und der Status der jeweiligen Seite. Letzterer regelt die Sichbarkeit der Seiten nach dem „Backprozess“. Wem das Standardtemplate nicht gefällt, kann dieses mittels der Templatesprachen Freemaker, Groovy Simple, Groovy Markup, Thymeleaf und Jade seinen Wünschen nach anpassen.
Wenn wir nun zurück auf den Buildprozess schauen, können wir zum Abschluss dieses ersten Teils den Build-Task mit dem Bake-Task verbinden.

build.dependsOn bake

Wenn wir nun den Build-Task ausführen, wird auch die Dokumentation erstellt. Im zweiten Teil werden wir weitere Zutaten für eine agile, frisch gebackene Dokumentation hinzufügen.

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

Daniel Kocot

Daniel ist seit Oktober 2016 ein Teil des Teams der codecentric am Standort in Solingen. Über 15 Jahre setzt er sich mit IT-Herausforderungen und deren Lösungen auseinander.

Share on FacebookGoogle+Share on LinkedInTweet about this on TwitterShare on RedditDigg thisShare on StumbleUpon

Kommentare

Kommentieren

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.