3 Minuten Lesezeit (623 Worte)

Eclipse Asciidoctor Editor: Effizient dokumentieren mit AsciiDoc

Freitag, 23. April 2021

Wie bereits in den Artikeln "Docs as Code - Dokumentation mit Asciidoctor" und "Quellcode in AsciiDoc einbinden" vorgestellt, lassen sich mit AsciiDoc und Asciidoctor sehr effektiv Dokumentationen von Software oder DV-Konzepten erstellen. Wie es sich für jede gute Markup-Language oder Programmiersprache gehört, hilft ein entsprechender Editor mit Syntax-Highlighting, Content-Assistant und sofortiger Kennzeichnung von Fehlern direkt bei der Eingabe, damit dies auch effizient gelingt, Spaß bereitet und möglichst wenig Frust verursacht.

Natürlich gibt es auch für AsciiDoc entsprechende Editoren bzw. Plugins für die gängigen IDEs, Texteditoren etc. In diesem Artikel schauen wir uns daher das Plugin für Eclipse IDE an: Eclipse Asciidoctor Editor.

Das Plugin lässt sich einfach über den Eclipse Marketplace installieren und verknüpft sich anschließend mit Dateien mit den Endungen .adoc und .asciidoc. Zusätzlich werden auch die PlantUML-Formate .plantuml, .pu, .puml, .iuml und das DITAA-Format .ditaa unterstützt.

Werfen wir zunächst einen Blick auf einen Screenshot und schauen uns an, wie das Ganze dann in Eclipse aussieht:

Eclipse-Plugin Asciidoctor Editor

Wie zu erkennen, teilt das Plugin den Arbeitsbereich in zwei Spalten auf. Links finden wir den eigentlichen Texteditor mit seiner farblichen Syntaxhervorhebung und rechts wird eine Vorschau des gerenderteren Dokuments dargestellt. Neben den eigentlichen Textanweisungen von AsciiDoc werden auch DITAA-Grafiken und PlantUML-Diagramme in der Vorschau gerendert.

Im oberen Bereich des Editors finden wir noch eine spezielle Symbolleiste, die eine direkte Formatierung oder das Einfügen von Tabellen per Mausklick erlauben.

Von links beginnend, lassen sich direkt Überschriften einfügen, Texte kursiv, fett oder als Code formatieren oder Zeilenumbrüche ergänzen. Ganz praktisch ist das Tabellen-Symbol. Damit lässt sich das Grundgerüst für eine Tabelle erstellen. Nach Klick auf die Schaltfläche fragt ein Dialog nach der Anzahl der Spalten und Zeilen. Die erstellte Tabellenvorlage sieht dann z. B. so aus:

[options="header",cols="1,1,1"]
|===
|HeadA   |HeadB   |HeadC   
//----------------------
|Row1A   |Row1B   |Row1C   
|Row2A   |Row2B   |Row2C   
|Row3A   |Row3B   |Row3C   
|===

Das blaue Kreissymbol mit dem weißen Info-I in der Mitte erlaubt das komfortable Einfügen von sog. "Admonitions" (Hinweise, Warnungen etc.) mit einem vorangestellten Icon. In AsciiDoc sieht dies dann so aus:

TIP: some nice text to show inside admonition...
NOTE: some nice text to show inside admonition...
IMPORTANT: some nice text to show inside admonition...
WARNING: some nice text to show inside admonition...
CAUTION: some nice text to show inside admonition...

Gerendert könnte das dann wie folgt dargestellt werden:

Die Schaltfläche mit dem Symbol <> dient zum Hinzufügen eines Templates für einen Code-Block. Nach dem Klick fragt ein Dialog zunächst nach dem Typ bzw. der Sprache. Java, Ruby, XML und JSON stehen aktuell zur Auswahl. Für Java wird folgendes Template generiert:

[source,java]
----
package com.acme.example; // <1>

public class HelloWorld {

    public static void main(String[] args) { // <2>

         System.out.println("Hello World!"); // <3>

    }
}
----
<1> Package definition
<2> Main method with arguments
<3> Print string to system output

Das führt gerendert zu folgenden Ergebnis:

Zusätzlich besteht noch die Möglichkeit, die Vorschau direkt per Mausklick als HTML oder PDF im Browser anzeigen zu lassen.

Fazit

Die Erstellung von professionellen Dokumentationen mit AsciiDoc ist relativ einfach möglich. Prinzipiell können AsciiDoc-Dateien mit jedem beliebigen Texteditor erstellt werden. Für ein effizientes Arbeiten empfiehlt sich allerdings ein Editor-Plugin, das die entsprechende Unterstützung bei der Erstellung von AsciiDoc-Dateien bietet. Hier wurde der Eclipse Asciidoctor Editor vorgestellt.

Selbstverständlich gibt für andere beliebte IDEs (z. B. IntelliJ IDEA, Atom, Visual Studio Code) ebenfalls entsprechende Plugins. Auch besteht die Möglichkeit, über Browser-Plugins (z. B. "Asciidoctor.js Live Preview" für Mozilla Firefox oder Google Chrome) den AsciiDoc-Code direkt im Browser zu rendern. Ebenfalls ist mit asciidocLIVE ein reiner Online-Editor verfügbar. Eine gute Übersicht befindet sich dazu auf der offiziellen Asciidoctor-Webseite.

{loadmoduleid 179}