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 .
War dieser Beitrag hilfreich?
Weitere Beiträge
von Daniel Kocot
20.11.2024 Dein Job bei codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
Weitere Artikel in diesem Themenbereich
Entdecke spannende weiterführende Themen und lass dich von der codecentric Welt inspirieren.
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-Autor*in
Daniel Kocot
Senior Solution Architect / Head of API Consulting
Du hast noch Fragen zu diesem Thema? Dann sprich mich einfach an.
Du hast noch Fragen zu diesem Thema? Dann sprich mich einfach an.