Asciidoctor met Plantuml

2018-02-17

Elke ontwikkelaar zal af en toe documentatie moeten schrijven, vaak ook met (UML) diagrammen. Een nadeel van een tool als Word is dat het niet handig samenwerkt met versiebeheersystemen. Nog lastiger zelfs om onder versiebeheer te zetten, zijn diagrammen. Mijn ervaring is daarnaast dat ik (te)veel tijd kwijt ben aan het leren werken met de tools voor diagrammen.

Asciidoctor is een tool waarmee je in een simpele taal, nette documenten kunt schrijven. De taal lijkt wat op Markdown en is erg laagdrempelig. Je kunt er verschillende plugins voor vinden, waaronder plugins voor het genereren van diagrammen. Voor Plantuml bestaat er zo'n plugin. Ze hebben Plantuml even eenvoudig gemaakt als hun website. En behalve Asciidoctor zijn er nog veel andere integratiemogelijkheden.


Aan de slag!

Asciidoctor met diagrammen heb je binnen enkele minuten opgezet, ik nodig je uit om dit te doen! Om je te helpen heb ik hieronder een route uitgestippeld:

  1. Download en installeer Ruby:

    https://www.ruby-lang.org/en/downloads/

  2. Installeer asciidoctor met behulp van de Ruby package manager:

    $ gem install asciidoctor

  3. Installeer de asciidoctor diagram extension:

    $ gem install asciidoctor-diagram

    Je hebt nu alle benodigdheden geïnstalleerd.

  4. Maak een ergens een directory aan met daarin het volgende:

    * src/jouw_document.adoc (dit is de broncode van jouw document)
    * dist (dit is de directory waar we de output plaatsen)
    * build.rb (dit is een Ruby file om jouw broncode te parsen)

  5. Open build.rb in een tekst editor. Plaats hierin de volgende content:

    require 'asciidoctor-diagram/plantuml'
    Asciidoctor.convert_file('src/jouw_document.adoc', :safe => 'unsafe', :to_dir => 'dist')


    De eerste regel is nodig om aan te geven dat we de diagram extension gebruiken. Regel twee converteert de broncode naar html en plaatst het resultaat in een
    aparte directory 'dist'.

  6. Open jouw_document.adoc in een editor, bijvoorbeeld Notepad. Om te testen of het maken van diagrammen werkt, zet de volgende content in jouw document:

    == Common knowledge
    ["plantuml", "asciidoctor-diagram-classes", "svg"]
    ----
    Man -> Beer : drink
    Beer -> Man : effect
    ----


    Alles is nu klaargezet. We kunnen testen of onze opstelling werkt.

  7. Run build.ruby:

    $ ruby build.rb

    Open dist/jouw_document.html voor het resultaat!

Fraai, en nu?

Nu kun je jouw document opbouwen met asciidoctor. Ik heb in deze blog 1 manier geschetst om met asciidoctor te werken. Natuurlijk zijn er meerdere wegen naar Rome. Je bent ook niet gebonden aan html, maar je kunt bijvoorbeeld ook PDFs genereren.

Ik heb in mijn voorbeeld Plantuml gebruikt. Er zijn echter nog meer diagram libraries beschikbaar, zoals graphviz of mermaid.

Mijn bevindingen

Als je eenmaal op gang bent, dan kun je zeer eenvoudig mooie documenten met diagrammen maken. De documentatie van de tool vind ik echter wat minder. Ik vind het voor iemand zonder Ruby kennis (zoals ik) wel een uitzoekwerk om het werkend te krijgen. Maar als je eenmaal doorhebt hoe het werkt, heb je het zo aan de praat en werkt het erg goed!

Links

https://asciidoctor.org/
http://www.rubydoc.info/gems/asciidoctor-diagram/1.4.0
http://asciidoctor.org/docs/user-manual/#api
http://plantuml.com/


Bekijk alle posts van Ramon