© StonePictures/Shutterstock.com
Kolumne: Hitchhiker’s Guide to Docs as Code

Kolumne: Hitchhiker’s Guide to Docs as Code


„Jede hinreichend fortschrittliche Technologie ist von Magie nicht zu unterscheiden.“ Dieses Zitat von Arthur C. Clarke trifft auf vieles zu, was ein modernes Build-Skript stellenweise leistet. In dieser Folge unserer Kolumne lüften wir das Geheimnis und erklären einige der nützlichen Gradle-Features, die Sie für Ihre Dokumentation verwenden können. Sollte das Ihr erstes Date mit Gradle sein, empfehlen wir zuerst die Lektüre einer entsprechenden Einführung [1].

Anatomie eines Build-Skripts

Listing 1 zeigt ein typisches Build-Skript für eine Spring-Boot-Anwendung, erstellt über den Spring Initializr [2]. Auffällig sind die doppelten Abschnitte repositories und dependencies. Der erste der beiden – innerhalb des buildscript {}-Abschnitts – ist für die Abhängigkeiten während des Builds zuständig und somit für Sie interessant. Der zweite Abschnitt definiert die Abhängigkeiten des Codes, der gebaut wird. Da Sie Dokumentation bauen, werden Sie diesen Abschnitt nicht benötigen.

Listing 1: Spring Boot Build

buildscript { ext { springBootVersion = '1.5.10.RELEASE' } repositories { mavenCentral() } dependencies { classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}") } } apply plugin: 'groovy' apply plugin: 'org.springframework.boot' group = 'com.example' version = '0.0.1-SNAPSHOT' sourceCompatibility = 1.8 repositories { mavenCentral() } dependencies { compile('org.springframework.boot:spring-boot-starter-web') compile('org.codehaus.groovy:groovy') testCompile('org.springframework.boot:spring-boot-starter-test') }

Auch der apply-plugin-Abschnitt wird für den Docs-as-Code-Ansatz benötigt. Listing 2 zeigt einen Ausschnitt aus dem docToolchain-build.gradle-File [3], in dem das AsciiDoc-Plug-in definiert und über die Abhängigkeiten um das Diagramm- und PDF-Plug-in ergänzt wird (ja, auch htmlSanityCheck wird als Plug-in referenziert).

Listing 2: Asciidoctor Dependencies

plugins { id "org.asciidoctor.convert" version "1.5.3" id "org.aim42.htmlSanityCheck" version "0.9.7" } dependencies { asciidoctor 'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.15' asciidoctor 'org.asciidoctor:asciidoctorj-diagram:1.5.4.1' }

Für die AsciiDoc-Plug-ins ist dabei die Definition mit asciidoctor wichtig, damit alles funktioniert. Sie wird anstelle der Ausdrücke genutzt, die man von Java her kennt, wie compile oder runtime.

Gradle bringt viele Tasks für die gängigsten Aufgaben eines Build-Systems mit. Wir wollen Ihnen hier kurz zeigen, wie Sie zu ganz individuel...

Neugierig geworden?

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang