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

Kolumne: Hitchhiker’s Guide to Docs as Code


Ein halbes Dutzend Folgen dieser Kolumne, bevor wir endlich zum Thema Sourcecode kommen: Wir möchten in Architekturdokumentation an manchen Stellen Code integrieren, etwa zur Beschreibung wichtiger Schnittstellen. AsciiDoc bietet hierfür schicke Features. Wie immer finden Sie den Quellcode dieser Kolumne online unter [1]. Unsere Beispiele übersetzen wir mit Gradle, und wieder haben wir einen Default Task für Asciidoctor konfiguriert:

> cd folge-7 > gradle 

Der AsciiDoc-Prozessor erzeugt den HTML-Output im Verzeichnis build/asciidoc/html5/, auch das kennen Sie ja schon.

Code in der (Architektur-)Doku?

Auch wenn Architekturdokumentation für Überblick im Großen sorgen soll, benötigen wir an manchen Stellen doch detaillierte Infos auf Ebene von Quellcode. Daher möchten wir an einigen Stellen Code(fragmente) in die Architekturdokumentation integrieren, beispielsweise für folgende Anwendungsfälle: Schnittstellen, Erläuterung technischer Konzepte und spezielle Lösungsansätze für (wiederkehrende) Aufgaben mit Architekturrelevanz. Schauen wir uns an, wie das mit AsciiDoctor grundsätzlich funktioniert.

Sourcecode anzeigen

Bevor wir mit echtem Sourcecode loslegen, müssen wir AsciiDoc mitteilen, welche Bibliothek wir für Syntax-Highlighting verwenden möchten – es werden z. B. CodeRay, highlight.js, Pygments und diverse andere Highlighter unterstützt. Fügen Sie im Header Ihres AsciiDoc-Dokuments folgende Deklaration ein:

= HHGDAC: Sourcecode integrieren :source-highlighter: coderay

Die konkrete Wahl des Highlighters [3] hängt hauptsächlich von den benötigten Ausgabeformaten und den in Ihrem Projekt verwendeten Sprachen ab.

So, jetzt sind wir bereit für Real Stuff: In AsciiDoc zeichnen Sie Sourcecode durch die Angabe von [source, <language>] aus. Der nachfolgende Block wird dann als Codeblock formatiert (die ---- markieren Anfang und Ende eines Blocks), das Ergebnis finden Sie in Abbildung 1.

[source,python] ---- # This program prints Hello, world! print('Hello, world!')

----

mueller_starke_hhgdac_1.tif_fmt1.jpgAbb. 1: So wird Code gerendert

Die Sprache festlegen

Um das Syntax-Highlighting von AsciiDoctor zu verbessern, können Sie die Programmiersprache als zweiten Parameter in der [source, <language>]-Deklaration angeben. AsciiDoc (beziehungsweise die jeweiligen Source Highlighter) können sich dann (noch) besser auf die jeweilige Syntax einstellen. In Listing 1 finden Sie das passende Beispiel, ausnahmsweise mal für die Sprache Go. Unserer Erfahrung nach sind die gängigen Highlighter relativ gut darin,...

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