Asciidoctor

Het schrijven van documentatie wordt door ontwikkelaars vaak ervaren als een noodzakelijk kwaad. Terwijl het toevoegen van commentaar in de code vaak wel wordt gedaan en dat toch ook een vorm van documenteren is. Maar dan zit je al in de code, waar je het liefst bent en dan is het niet zo moeilijk om even wat toe te voegen. Maar documentatie die code overstijgend is, blijft vaak een ondergeschoven kindje.

In dit artikel ga je zien hoe Asciidoctor kan helpen bij het schrijven van documentatie. Eerst zie je wat de werkwijze is om tekst te schrijven. Dan zie je nog hoe dit geïntegreerd kan worden met Java en tools die gebaseerd zijn op Java.

 

Documentatie is belangrijk

Het nut van documentatie is wel duidelijk voor de meeste mensen. Bijvoorbeeld een beschrijving van de applicatie binnen een groter IT landschap, met daarin de koppelingen met externe systemen beschreven. Of een beschrijving van de gebruikers die de applicatie gebruiken en op welke manier ze de applicatie kunnen gebruiken. Toen het Agile Manifesto kwam met daarin het statement dat werkende software geprefereerd werd boven documentatie, is dit vaak opgevat als het totaal niet meer schrijven van documentatie.

Waarom wordt het schrijven van documentatie dan toch zo vaak uitgesteld of helemaal niet gedaan? Dit heeft onder andere te maken met de tooling die je daarvoor moet gebruiken. In het ergste geval moet je een tekstverwerker gebruiken, zoals Microsoft Word of Libre Office Writer. Met een tekstverwerker ben je ironisch genoeg meer bezig met het bewerken van de tekst dan het schrijven van de tekst. Je moet rekening houden met bepaalde styling en daarnaast zijn veel opties en acties niet toegankelijk met het toetsenbord. Ook moet je bezig zijn met de opmaak van je documentatie.

Een andere oplossing is om geen tekstverwerker te gebruiken, maar om je documentatie te schrijven in bijvoorbeeld Docbook. Docbook biedt een structuur aan om je content in XML te schrijven. Het voordeel is dat je niet bezig hoeft te zijn met styling en opmaak van je document, maar de tekst van je document is niet zo goed leesbaar door alle XML tags die ook aanwezig zijn.

Bij het schrijven van documentatie over technische zaken is het vaak moeilijk om deze up-to-date te houden. In de documentatie heb je bijvoorbeeld een verwijzing opgenomen naar een stuk source code door de code te kopiëren uit je IDE en te plakken in de documentatie. Maar de source code kan intussen al aangepast zijn, waardoor de documentatie niet meer de juiste code bevat en dus achterhaald is.

Het zou toch mooi zijn als je documentatie zou kunnen schrijven op dezelfde manier als je ook je code schrijft. Geen afleiding door zaken zoals styling en opmaak, maar wel de echte inhoudelijke documentatie schrijven. Of verwijzingen opnemen naar echte source code en dat deze automatisch in de documentatie wordt bijgewerkt wanneer de source code ook is aangepast. Met Asciidoctor kunnen we al deze doelen bereiken.

 

Wat is Asciidoctor?

Asciidoctor is een complete tool die het mogelijk maakt om documenten die in een bepaalde plain text markup zijn beschreven te transformeren naar verschillende output formaten. De markup is Asciidoc dat al vele jaren bestaat en is ontstaan in 2002. Asciidoc is een plain text formaat, vergelijkbaar met Markdown. Asciidoc heeft zelf al een aantal handige features waardoor je het kunt gebruiken voor het schrijven van kleine artikelen, maar ook complete boeken. We zullen in dit artikel ook zien dat Asciidoctor de Asciidoc markup ook nog wat heeft uitgebreid met eigen handige features.

Asciidoctor heeft ook de mogelijkheid om een Asciidoc markup document te transformeren naar HTML5, Docbook, PDF, ePub en andere formaten. Dit betekent dat we, wanneer we eenmaal onze documentatie met Asciidoctor hebben geschreven, verschillende output formaten kunnen genereren van dezelfde bron documentatie. Indien er specifieke eisen zijn voor styling van documentatie bij een project dan is deze transformatiestap de ideale plek om daaraan te kunnen voldoen. Dus je bent niet langer in het bron document bezig met opmaak en styling, maar dit pas je toe in de transformatiefase. Hierdoor kun je heel gericht bezig zijn met de content van je document in plaats van je te laten afleiden door randzaken.

In het volgende voorbeeld zie je een simpel Asciidoctor document waarbij je meteen kunt zien hoe leesbaar de markup is:

= Asciidoctor voorbeeld
 
Het schrijven van documentatie
met Asciidoctor is makkelijk.
 
== Taken
 
* Schrijf artikel
* Publiceer artikel
 
[TIP]
Probeer http://asciidoctor.org[Asciidoctor]
en kijk of je het leuk vindt.
 
[source,java]
----
System.out.println("Java Magazine.");
----

Listing 1

Wanneer je deze Asciidoctor markup converteert naar HTML5 dan krijg je het volgende te zien in je web browser:

 

Voorbeeld HTML5 output

 

Document-attributen

Een Asciidoctor document heeft ook zogenaamde document-attributen. Dit zijn eigenlijk een soort variabelen die je kunt definiëren en gebruiken in je document. Stel je voor dat je een technisch document schrijft en daarin wordt een aantal keer een bepaalde URL gebruikt. Nu kan je deze URL elke keer opnieuw intikken, maar je kan er ook een document attribuut van maken en dan een verwijzing naar het document attribuut gebruiken in je tekst. Het grote voordeel hiervan is dat je geen typefouten kan maken, maar ook dat je de waarde kan aanpassen op 1 plek en dat deze in het hele document wordt bijgewerkt.

Je definieert een document-attribuut door de naam van het attribuut tussen twee dubbele punten (:) te zetten, gevolgd door de waarde. Je maakt een verwijzing naar een document attribuut door de naam tussen accolade openen en sluiten ({}) te zetten.

In het volgende voorbeeld wordt een document attribuut jdriven-url gedefinieerd en gebruikt:

= Document attribuut
 
:jdriven-url: http://www.jdriven.com/
 
Verwijzing naar de {jdriven-url}[Website].
Contact via {jdriven-url}/contact[Contact pagina].

Listing 2

Asciidoctor heeft zelf ook al een aantal document-attributen die gebruikt worden, zoals configuratie-variabelen. Je kan bijvoorbeeld de nummering van headings aan of uit zetten door gebruik te maken van het attribuut numbered.

 

Include source bestanden

In technische documentatie is het niet ongebruikelijk om iets uit te leggen aan de hand van een stuk voorbeeldcode. Normaal gesproken zou je de code uit het source bestand kopiëren en plakken in de tool waarmee je je documentatie schrijft. Met Asciidoctor kunnen we vanuit de Asciidoctor markup verwijzen naar het echte source bestand en daarvan de inhoud of een gedeelte van de inhoud toevoegen aan onze documentatie. Je gebruikt hiervoor de zogenaamde include directive van Asciidoctor met een verwijzing naar het bestand dat je wilt toevoegen. De verwijzing naar het bestand kan een absolute pad zijn of een relatief pad ten opzichte van het Asciidoc markup document. Het mooie is dat je nu in je documentatie altijd de laatste versie van de source code hebt staan, maar ook dat je de source code die in je documentatie staat getest kan hebben.

Om nog wat extra uitleg over een regel code toe te voegen, kan je een callout in Asciidoctor gebruiken. Een callout wordt gebruikt om iets uit te leggen en bestaat uit een verwijzing plus een beschrijving die hoort bij de verwijzing. In de source code wordt aangegeven waar een callout moet komen en in het Asciidoctor document kan je tekst voor de callout schrijven.

In het volgende voorbeeld hebben we een kort stuk Java code met daarin een callout aangegeven in het commentaar als <1>:

 

package com.jdriven.asciidoctor;
 
public class Sample {
    public static void main(final String[] args) {
        System.out.println("Asciidoctor is awesome!") // <1>
    }
}

Listing 3

En in de volgende Asciidoctor markup gebruiken we de include directive met een verwijzing naar het Java source bestand, gevolgd door een beschrijving voor de callout:

 

= Java listing
 
Een voorbeeld Java listing
van een extern bestand.
 
.`Sample.java`
[source,java]
----
include::Sample.java[]
----
<1> Toon tekst in console

Listing 4

Als je de HTML5 output ziet na een transformatie, dan zie je de callout en hoe syntax highlighting is toegepast op de Java source:

 

Voorbeeld HTML5 output met Java code

 

Asciidoctor en Java

Asciidoctor is geschreven in Ruby en kan gemakkelijk worden geïnstalleerd als RubyGem. Via de commandline kan je dan een document transformeren. Maar het meest interessante – vanuit een Java oogpunt gezien – is dat Asciidoctor dankzij JRuby en de AsciidoctorJ library ook beschikbaar is op het Java platform. Dit betekent dat we Asciidoctor kunnen aanroepen vanuit onze eigen applicatie code, maar ook dat build tools als Gradle en Maven gebruikt kunnen worden om documenten te transformeren.

In het volgende voorbeeld zie je hoe je de Asciidoctor Gradle plugin kan definiëren om meerdere documenten uit de src/docs/asciidoc directory te transformeren:

 

buildscript {
    repositories.jcenter()
 
    dependencies {
        classpath 'org.asciidoctor':asciidoctor-gradle-plugin:1.5.2'
    }
}
 
apply plugin: 'org.asciidoctor.convert'

Listing 5

De plugin voegt een nieuwe taak asciidoctor toe die we kunnen uitvoeren met Gradle. Er zijn verschillende configuratiemogelijkheden, zoals aangeven welke documenten geconverteerd moeten worden, document attributen definiëren en het output formaat aangeven.

 

Extensions

Nu heeft Asciidoctor al veel te bieden, maar je kan zelf ook nog de functionaliteit van Asciidoctor uitbreiden met extensies. Asciidoctor biedt namelijk een extensie API aan. Je kan een extensie schrijven in Ruby of een JVM taal, zoals Java of Groovy. Er zijn verschillende plekken in het proces waarvoor je een extensie kan schrijven. Bijvoorbeeld als het hele document is verwerkt door Asciidoctor, maar nog niet als bestand is opgeslagen. Of wanneer een blok tekst wordt verwerkt met een eigen blok stijl. Of je schrijft je eigen zogenaamde inline macro om bijvoorbeeld automatisch een link naar een issuemanagement systeem op te nemen.

 

Wie gebruikt Asciidoctor?

GitHub gebruikt Asciidoctor. Ze gebruiken het zelf om de helppagina’s te maken, maar je kan ook Asciidoctor markup gebruiken voor bijvoorbeeld de README van je project. GitHub zal bij het renderen van de pagina in HTML de markup herkennen en met behulp van Asciidoctor transformeren. Dit werkt trouwens ook voor Gists die je schrijft.

De Spring Getting Started Guides zijn tegenwoordig ook allemaal geschreven in Asciidoctor en een hoop van de Spring documentatie wordt nu herschreven van Docbook naar Asciidoctor. Een uitgever zoals O’Reilly maakt het ook mogelijk voor auteurs om de teksten voor hun boeken aan te leveren in Asciidoctor formaat.

Eén van de bezwaren om documentatie te schrijven is dat WYSIWYG editors niet aansluiten bij het dagelijkse proces van ontwikkelaars. Door het gebruik van Asciidoctor kan dat bezwaar worden weggenomen. Wanneer je een document schrijft met behulp van Asciidoctor weet je dat je je alleen op de inhoud en structuur hoeft te concentreren. Je kan het document ook toevoegen aan je versiebeheersysteem, want het is gewoon tekst, zodat je ook gemakkelijk kan zien wat de wijzigingen zijn tussen verschillende versies.

Asciidoctor heeft ook handige features, zoals het kunnen toevoegen van externe bestanden die goed aansluiten bij het schrijven van technische documentatie. En door de extensie API is het zelfs mogelijk om dingen te doen met je document die nu nog niet standaard met Asciidoctor gedaan kunnen worden. En gelukkig is het door de AsciidoctorJ library mogelijk om hiervoor Java of een andere JVM taal te gebruiken.

Als je document klaar is, kan je nog kiezen voor een HTML versie, PDF of ePub als output. Er zijn ook al templates beschikbaar die een document naar Word formaat kunnen transformeren. Maar omdat dit een los proces is dat je uitvoert na het schrijven van de tekst hoef je helemaal niet meer bezig te zijn met opmaak als je je tekst schrijft.

De transformatie van een document kan ook gemakkelijk worden meegenomen in een build proces door de Gradle en Maven plugins die beschikbaar zijn.

Asciidoctor maakt de drempel om documentatie te schrijven een stuk lager en sluit goed aan bij de belevingswereld van ontwikkelaars. Probeer in je huidige of volgende project eens om Asciidoctor toe te voegen aan je gereedschapskist en beschrijf de mooie dingen die je aan het maken bent.