Kolumne

Lagebericht Eclipse-IDE: Technische Dokumentation mit AsciiDoc, Gradle und Eclipse

Lars Vogel, Albert Tregnaghi

©s&s_media

Kein Projekt kommt ohne Dokumentation aus – sei es, um mit ihrer Hilfe die Kundenanforderungen zu erfassen, sei es um ein Testszenario zu beschreiben.

Aus Entwicklersicht sind die Anforderungen klar: Technische Dokumentationen sollten in Textformaten ausgegeben werden, da sie sich so unter Versionsverwaltung stellen lassen. Aus Konsumentensicht sollte es möglich sein, aus Textformaten ansprechende Zielformate wie HTML- oder PDF-Dokumente zu generieren. Die Lösung: Der Entwickler schreibt die Dokumentation mithilfe seiner bevorzugten IDE, die bestenfalls entsprechende Zielformate ausgeben kann. Wir zeigen, wie das mit AsciiDoc, Gradle und Eclipse effizient möglich ist.

Was steckt hinter AsciiDoc und Asciidoctor?

Bei AsciiDoc handelt es sich um ein rein textuelles Beschreibungsformat für Dokumente. Die leicht verständliche Syntax garantiert selbst für aufwendige Dokumentationen im reinen Textformat eine gute Lesbarkeit. So existieren beispielsweise AsciiDoc-Buchvorlagen von O’Reilly, mit deren Hilfe Autoren ihre Bücher gestalten können. Neben den typischen Ausgabeformaten wie PDF und HTML ist es mit AsciiDoc sogar auch möglich, komplette Präsentationen ganz ohne PowerPoint zu erzeugen. Abbildung 1 zeigt ein typisches AsciiDoc-Dokument.

Abb. 1: „einanderesfile.adoc“ muss hier natürlich im gleichen Verzeichnis liegen

Abb. 1: „einanderesfile.adoc“ muss hier natürlich im gleichen Verzeichnis liegen

Mehr zur Syntax findet man im AsciiDoc-Tutorial, Writer’s Guide und in der Syntax Quick Reference. Die wohl bekannteste Tool-Chain, um AsciiDoc-Dokumente zu parsen und in andere Ausgabeformate zu transferieren, ist Asciidoctor.

Dokumentation bauen mit Gradle

Wer die Dokumentationserzeugung ohne großen Aufwand automatisieren möchte, sollte das in Gradle integrierte Asciidoctor-Gradle-Plug-in nutzen. Das folgende build.gradle-File reicht aus, um das in Abbildung 1 dargestellte Dokument in HTML zu konvertieren (Listing 1).

buildscript {
  dependencies {
    classpath 'org.AsciiDoctor:AsciiDoctorj-pdf:1.5.0-alpha.15'
  }
}

plugins {
  id 'org.AsciiDoctor.convert' version '1.5.6'
}

apply plugin: 'java'
apply plugin: 'org.AsciiDoctor.convert'

version = '1.0.0-SNAPSHOT'

AsciiDoctorj {
  version = '1.5.6'
}

AsciiDoctor {
  attributes \
  'source-highlighter': 'coderay'
    sourceDir = file('.')
    sources {
      include '*.adoc'
    }
  backends = ['html','pdf']
}

Ist Gradle auf der Kommandozeile installiert, lassen sich mit diesem File bereits gelungene PDF- (Abb. 2) und HTML-Dateien ausgeben: einfach gradle Ascii-Doctor aufrufen. Alternative Outputformate sind DocBook und EPUB. Weitere Optionen des Gradle-Build-Files sind online beschrieben.

Abb. 2: Ausschnitt des PDF-Outputs

Abb. 2: Ausschnitt des PDF-Outputs

Lässt man sourceDir im build.gradle-File weg, wird standardmäßig in ./src/main/AsciiDoc nach AsciiDoc-Files gesucht. Dieses Setup ist sinnvoll, wenn die Dokumentation direkt in den Source-Projekten abgelegt werden soll.

Asciidoctor Editor: Installation und Benutzung

Alternativ lässt sich AsciiDoc auch elegant mit Eclipse schreiben. Seit Mitte März 2018 steht zu diesem Zweck ein spezialisiertes Eclipse-Plug-in zur Verfügung: Asciidoctor Editor. Die aktuelle Version ist im Eclipse Marketplace zu finden. Das Projekt selbst wurde auf GitHub veröffentlicht. Nach der Installation sind Erstellung und Anzeige von AsciiDoc-Dokumenten sofort möglich. Es spielt dabei keine Rolle, in welcher Perspektive oder in welcher Art von Projekt man sich gerade befindet.

Speichert der Nutzer das Dokument, aktualisiert der Editor die Vorschau und generiert sie intern als HTMLAusgabe. Für die Vorschau des Dokuments stehen dabei mehrere Darstellungsmöglichkeiten zur Verfügung: So kann der Nutzer über den Splitscreen eine horizontale oder vertikale Vorschau im Editor selbst nutzen oder aber den Systembrowser (Abb. 3) verwenden, der mehr Platz zum Editieren bietet.

Abb. 3: Asciidoctor-Editor: spezialisiertes Eclipse-Plug-in

Abb. 3: Asciidoctor-Editor: spezialisiertes Eclipse-Plug-in

Die Toolbar des Editors hält neben Layouteinstellungen weitere kleine Hilfsmittel bereit. So lassen sich diverse Blöcke für Tabellen, Links, Code-Snippets etc. per Knopfdruck erzeugen. Der Editor selbst bietet einfache Codevervollständigung, spezifische Tooltipps und Syntax-Highlighting. Mithilfe des Schlüsselworts include lassen sich eingebundene Dokumente mittels CTRL + Klick in einem neuen Editor öffnen.

Asciidoctor bietet die Möglichkeit, ditaa-, PlantUMLoder auch Graphviz-Inhalte direkt zu integrieren. Der Eclipse Editor zeigt diese in der Preview mit an (Abb. 4). Dabei ist zu beachten, dass sowohl für die Darstellung von Graphviz- als auch PlantUML-Inhalten die Installation von Graphviz erforderlich ist.

Abb. 4: Integrierte Inhalte landen direkt in der Vorschau

Abb. 4: Integrierte Inhalte landen direkt in der Vorschau

Diagramme lassen sich auch über die jeweiligen Diagrammmakros einbinden (Abb. 5).

Abb. 5: Eingebundene Diagramme lassen sich in verschiedenen

Abb. 5: Eingebundene Diagramme lassen sich in verschiedenen

Buildship: Installation und Benutzung

Ist die Dokumentation erst einmal in Eclipse geschrieben, scheint es wenig attraktiv, auf die Kommandozeile zu wechseln, um damit HTML- oder PDF-Output zu erzeugen (Abb. 6). Doch die Outputerzeugung ist auch in Eclipse möglich – mittels Gradle Tooling (Abb. 7). Sollte dieses in der Eclipse Distribution noch nicht vorinstalliert sein, lässt es sich einfach unter Help | Install New Software nachinstallieren. Im Anschluss einfach Quick Access mit CTRL + 3 anwählen und import gradle eingeben. Nun muss der Nutzer auf das Verzeichnis verweisen, in dem das Buildscript vom obigen Beispiel liegt, um schließlich das Ganze importieren zu lassen (Abb. 8) (Abb. 9).

Abb. 6: Um die eingebundenen Diagrammdateien editieren zu können, stellt das Eclipse-Plug-in Editoren für PlantUML und ditaa zur Verfügung

Abb. 6: Um die eingebundenen Diagrammdateien editieren zu können,
stellt das Eclipse-Plug-in Editoren für PlantUML und ditaa zur Verfügung

Abb. 7: Jetzt ist es möglich, die Generierung auf das Asciidoctor-Task im Gradle Task View zu triggern

Abb. 7: Jetzt ist es möglich, die Generierung auf das Asciidoctor-Task
im Gradle Task View zu triggern

Abb. 8: Per Default ist der Gradle Output Folder im Package- und Projekt-Explorer versteckt

Abb. 8: Per Default ist der Gradle Output Folder im Package- und
Projekt-Explorer versteckt

Abb. 9: Um den Output auch im Package- und Projekt-Explorer zu sehen, muss der Filter weggenommen werden

Abb. 9: Um den Output auch im Package- und Projekt-Explorer zu
sehen, muss der Filter weggenommen werden

Das Gradle Tooling führt keinen automatischen Refresh des Build Folder durch. Insofern ist es notwendig, auf dem Projekt einmal F5 auszuführen. Sollte das stören, hilft es, GitHub im Auge zu behalten und für das Issue zu stimmen.

Zusammenfassung

Unter Entwicklern ist das Schreiben von Dokumentationen nicht gerade populär. AsciiDoc nähert die missliebige Tätigkeit ans Programmieren an und könnte so für gute Entwicklerlaune sorgen. Hinzu kommen der neue Asciidoctor-Editor und das Gradle Tooling, die es ermöglichen, Dokumentationen in Eclipse zu schreiben und den gewünschten Output zu erzeugen. Sollte im Editor etwas fehlen, freut sich Albert Tregnaghi über entsprechende Pull Requests für seinen Asciidoctor-Editor bei GitHub.

Geschrieben von
Lars Vogel
Lars Vogel
Lars Vogel ist Geschäftsführer der vogella GmbH, die Kunden im Bereich Eclipse, Android und anderen Themen unterstützt. Als Project-Management-Committee-Mitglied, Eclipse-Projektleiter und Committer hilft er dem Eclipse-Projekt. E-Mail: lars.vogel@vogella.com
Albert Tregnaghi
Albert Tregnaghi
Albert Tregnaghi entwickelt seit fünfzehn Jahren Java und hat ein starkes Interesse an Open Source. Er ist verantwortlich für einige Plug-ins auf dem Eclipse Marketplace, unter anderem für den hier vorgestellten Asciidoctor-Editor. E-Mail: albert.tregnaghi@gmail.com
Kommentare

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
400
  Subscribe  
Benachrichtige mich zu: