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

Kolumne: Hitchhiker’s Guide to Docs as Code


In der letzten Ausgabe haben wir gezeigt, wie Sie mithilfe von AsciiDoc schnell zu ordentlich gestalteten Dokumenten kommen können. In der zweiten Folge unserer Kolumne möchten wir Ihnen Möglichkeiten zur Strukturierung und Modularisierung von Dokumentation vorstellen, was einerseits zur Erleichterung von Teamarbeit, andererseits zur Verwendung einzelner Dokuteile für verschiedene Zielgruppen dient. Im Gegensatz zu anderen Markup-Sprachen verfügt AsciiDoc über ein mächtiges Konzept zur Modularisierung: den Befehl include::path[attributes]. Damit können Sie Ihre Dokumentation auf mehrere Dateien aufteilen. Das erleichtert die Teamarbeit und verbessert die Übersichtlichkeit. Beispielsweise kann ein Masterdokument Verweise auf Unterdokumente erhalten (Listing 1). Darin inkludieren wir zwei AsciiDoc-Dateien (kapitel-1.adoc und kapitel-2.adoc). Wie üblich übersetzen wir unsere Dokumente mit Gradle:

> cd folge-2 > gradle asciidoctor

Der AsciiDoc-Prozessor erzeugt im Verzeichnis build/asciidoc/html5/ das passende HTML (Abb. 1). Dabei wurde einerseits das HTML-Dokument mit zwei Unterkapiteln erzeugt und zusätzlich noch das referenzierte Diagramm in das build-Verzeichnis kopiert. Hierzu nutzen wir wieder eine Standardeinstellung des Asciidoctor-Plug-ins für Gra­dle: Alle Dateien aus dem images-Verzeichnis werden automatisch in das build-Verzeichnis kopiert. Es bietet sich an, die Kapitel der Dokumentation wie im Beispiel mit dem eigentlichen Inhalt in Unterverzeichnisse zu legen. Dadurch ist das strukturierende Masterdokument sauber vom eigentlichen Inhalt getrennt. Auch das im AsciiDoc-Format vorliegende arc42-Template ist in dieser Struktur aufgebaut [1].

mueller_starke_hhgdac_1.tif_fmt1.jpgAbb. 1: HTML-Ausgabe des modularisierten Dokuments

Listing 1: „master.adoc“

:source-highlighter: coderay :imagesdir: images == Dies ist das Hauptdokument Durch verschiedene 'include'-Anweisungen modularisieren wir die Dokumentation: include::kapitel/kapitel-1.adoc[leveloffset=+1] include::kapitel/kapitel-2.adoc[leveloffset=+1]

Listing 2: „kapitel1.adoc“

== Kapitel 1: Übersicht Eine Übersicht ist immer nützlich... .Module unserer Dokumentation image::uebersicht.png[]

Listing 3: „kapitel2.adoc“

== Kapitel 2: Schnittstellen include::{sourcedir}SampleInterface.java[tag=signatur]

Listing 4: „SampleAILibrary.java“

package demo; class SampleAILibrary { // beantwortet alle Fragen // tag::signatur[] static String answerQuestion(String question) throws Exception // end::signatur[] { if (question==null) { //...

Source...

Exklusives Abo-Special

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