Folge 1: Docs-as-Code

Source und Infos zur JavaMagazin-Kolumne von R.D. Müller und G. Starke

Folge 1: Hitchhiker’s Guide to Docs as Code

Wir möchten Dokumentation in der Softwareentwicklung von vielerlei typischen Schmerzen befreien:

• Wir generieren Dokumente, beispielsweise Architektur-, Schnittstellen- oder Betriebsdokumentation.

• Wir arbeiten dabei DRY, modular und flexibel.

• Wir erzeugen zielgruppenspezifische Ergebnisse, u.a. in HTML, pdf, docx oder Confluence.

Voraussetzungen

• Gradle installiert zu haben, hilft ungemein…​ Wir bevorzugen die Installation über sdkman, den großartigen Package-Manager.

• Eine Shell/Kommandozeile/Terminal.

Einführung

Wir haben einen Wrapper für Gradle zugefügt - das macht den Einstieg für Sie noch einfacher:

cd folge-1
./gradlew asciidoctor

Falls Sie Gradle bereits installiert haben, geht’s auch so:

cd folge-1
gradle asciidoctor

Das Ergebnis, die Datei hello.html, wird ins Verzeichnis ./build/asciidoc/html5 generiert, und sollte etwa wie folgt aussehen: