In software development, one question that constantly arises is how the current project can be comprehensively documented. The most common way to do this is to use Confluence or some other wiki. But why not use the code itself?
This is why, in the first part of this article series, I will give you an understanding of JBake .
JBake is actually a generator for static websites. Dan Allen, Project Lead of the Asciidoctor project, calls it “Jekyll of the JVM”. Using plugins for Maven and Gradle, JBake can easily be integrated into build pipelines.
I will start off by explaining potential use cases of JBake based on an example. First and foremost, we will build a simple Gradle project to provide a starting point for further steps.
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'
}
Now we extend the build file by the plugin jbake-gradle-plugin.
plugins {
id 'org.jbake.site' version '1.0.0'
}
This gives us another “bake” task that allows us to “bake” the documentation. For this, we also need a JBake basic installation within the sources. Under MacOS, this can be easily done with SDKMAN
$ sdk install jbake
or Homebrew
$ brew install jbake
By default, the Gradle plugin expects the documentation sources to be located in src/jbake. By using parameters in the build file, the source and destination can be adjusted. The target, however, is always located in the build folder. For our example, we use the following values:
jbake {
srcDirName = 'src/documentation'
destDirName = 'documentation'
}
Since JBake is now installed, we can run the command
jbake -i
in the folder
src/documentation
The resulting structure can now be extended and adapted as desired. Content can be saved in the content folder in the form of HTML, Asciidoctor, or Markdown files. For this blog article, we will replace the existing file about.html with about.adoc and adjust the content accordingly.
= Project documentation
Daniel Kocot
2017-10-03
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published
Within the Asciidoctor document, it is possible to save JBake metadata such as page type, tags, and the status of each page. The latter controls the visibility of the pages after the “baking process”. If you do not like the standard template, you can customize it according to your own preferences using the template languages Freemaker, Groovy Simple, Groovy Markup, Thymeleaf, and Jade.
Now, looking back at the build process, we can connect the build task with the bake task to complete this first part.
build.dependsOn bake
If we now execute the build task, the documentation will be generated as well. In the second part, we will add more ingredients to our agile, freshly baked documentation.
Check out the demo in my Git Repository: agile-fresh-baked-docs .
Was this post helpful?
More articles
fromDaniel Kocot
11.12.2024 Your job at codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
More articles in this subject area
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.
Blog author
Daniel Kocot
Senior Solution Architect / Head of API Consulting
Do you still have questions? Just send me a message.
Do you still have questions? Just send me a message.