© BIRTHPIX/Shutterstock.com
Kolumne: Lagebericht Eclipse IDE

Kolumne: Lagebericht Eclipse IDE


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 [1]. 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 [2], 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.

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

Mehr zur Syntax findet man unter [3], [4] und [5]. Die wohl bekannteste Tool-Chain, um AsciiDoc-Dokumente zu parsen und in andere Ausgabeformate zu transferieren, ist Asciidoctor [6].

Dokumentation bauen mit Gradle

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

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 AsciiDoctor aufrufen. Alternative Outputformate sind DocBook und EPUB. Weitere Optionen des Gradle-B...

Neugierig geworden? Wir haben diese Angebote für dich:

Angebote für Gewinner-Teams

Wir bieten Lizenz-Lösungen für Teams jeder Größe: Finden Sie heraus, welche Lösung am besten zu Ihnen passt.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang