DEV Community

Jorge
Jorge

Posted on • Originally published at jorge.aguilera.soy on

Introducción a Asciidoc y Asciidoctor (5): diagramas

#asciidoc #documentation #write #diagram

| | Este post es la continuación a intro-asciidoctor-4.html |

| | Yo utilizo sistemas Linux por lo que los comando que indico para instalar software estan orientados a este.Si tienes interés en saber cómo hacerlo en Windows, escribeme y lo investigaré |

Objetivo

En este post veremos cómo crear diferentes tipos de diagramas usando sólo un editor de texto.

Los tipos de diagramas son variados y de diferentes ámbitos como:

  • Diagramas de clases, relaciones, actividades, etc tipicos de UML

  • Diagramas de arquitectura software

  • Diagramas Gant para organización de proyectos, tareas, equipos, etc

  • Representación de componentes UI (textbox, listbox, buttons, checks, etc)

  • Gramatica, para representar partes de una sintaxis por ejemplo

  • Otros

Requisitos

El primer requisito que necesitamos es tener instalado asciidoctor, tal como se ha explicadoen los post anteriores de esta serie.

| | Para este post vamos a usar asciidoctorj |

$sdk man install asciidoctorj

La instalacion de asciidoctorj incluye por defecto el segundo requisito que necesitaremos para dotar a nuestros documentosde diagramas, asciidoctor-diagram

En caso de que estés usando la versión ruby deberás instalar la gema correspondiente:

$ gem install asciidoctor-diagram

En realidad asciidoctor_diagram por si mismo NO genera ningun diagrama, sino que podriamos decir que es el "pegamento"entre asciidoctor y los diferentes generadores de diagramas. En la página oficial podemos ver los tipos soportados:

The extensions supports the AsciiToSVG, BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag),Ditaa, Erd, GraphViz, Mermaid, Msc, PlantUML, Shaape, SvgBob, Syntrax, UMLet, Vega,Vega-Lite and WaveDrom syntax.
Enter fullscreen mode Exit fullscreen mode

| | Esta lista no es exclusiva, pudiendo incorporar nuevos interpretes gracias al modelo de extensionesde Asciidoctor. Yo mismo he hecho alguna extension en Java y es realmente fácil |

Si utilizamos el método indicado anteriormente para la instalación de Asciidoctor (AsciidoctorJ) tendremos incluidospor defecto los diagramas Ditaa y PlantUML (tal vez algun otro) asi que si vamos a usar algun otro tipo tendremos quetener instalado el ejecutable correspondiente.

De forma generica, y como consejo, yo siempre instalo Graphviz puesto que muchos de estos generadores lo usan

$sudo apt-get install graphviz

Mermaid

Si por ejemplo queremos generar diagramas usando Mermaid tendremos que ejecutar:

$ npm install -g mermaid.cli

o si usamos yarn

$ yarn global add mermaid.cli

Syntrax

Por su parte, syntrax esta desarrollado en python por lo que tendremos que tener instalado este software y ejecutar

$pip install --upgrade syntrax

| | Efectivamente, como has podido adivinar te toca conocer la sintaxis de cada generador que quieras utilizar.Asciidoctor-diagram solo sirve como puente entre tu documento y el generador |

Sintaxis

La potencia de poder adjuntar a nuestra documentacion diagramas definidos en formato texto es inmensa, pudiendo aprovechartodas las caracteristicas propias de la filosofía "doc-as-code", es decir, crear y manejar nuestra documentación igualque lo hacemos con el código: editores de texto, versionable, mergear ramas, aprovaciones, despliegues continuos, etc

Include implícito

Asi pues la sintaxis para definir un diagrama a lo largo de nuestra documentación consiste simplemente en crear unbloque donde se especifique el tipo de diagrama que vamos a usar e incluir el cuerpo del diagrama dentro del mismo:

Por ejemplo:

Este parrafo es parte de nuestra documentacion, donde queremos poner a continuacion un diagrama de clases plantuml::fichero_mi_diagrama.txt[]
Enter fullscreen mode Exit fullscreen mode

donde fichero_mi_diagrama.txt puede ser un fichero de texto como el siguiente:

class Car Driver - Car : drives > Car *- Wheel : have 4 > Car -- Person : < owns
Enter fullscreen mode Exit fullscreen mode

De tal forma que nuestro documento se vería como:

Este parrafo es parte de nuestra documentación, donde queremos poner a continuación un diagrama de clases

diag ce10eaf325fe034a3c9fe082d7ae5d2e

Bloques

Si no quieres crear más ficheros también puedes usar bloques para incluir tus diagramas junto con la documentacion:

Este parrafo es parte de nuestra documentación, donde queremos poner a continuación un diagrama de clases [plantuml] ++++ class Car Driver - Car : drives > Car *- Wheel : have 4 > Car -- Person : < owns ++++
Enter fullscreen mode Exit fullscreen mode

Y el resultado sería el mismo.

Ejemplos

A continuacion algunos diagramas de ejemplos generados con Ditaa, PlantUML, Mermaid y Syntrax

Diseño Software

Procesos 

[ditaa] .... +-------------+ | Asciidoctor |-------+ | diagram | | +-------------+ | PNG out ^ | | ditaa in | | v +--------+ +--------+----+ /---------------\ | | --+ Asciidoctor +--> | | | Text | +-------------+ | Beautiful | |Document| | !magic! | | Output | | {d}| | | | | +---+----+ +-------------+ \---------------/ : ^ | Lots of work | +-----------------------------------+ ....
Enter fullscreen mode Exit fullscreen mode

Ditaa box

UML 

[plantuml] ++++ title Relationships - Class Diagram class Dwelling { +Int Windows +void LockTheDoor() } class Apartment class House class Commune class Window class Door Dwelling <|-down- Apartment: Inheritance Dwelling <|-down- Commune: Inheritance Dwelling <|-down- House: Inheritance Dwelling "1" *-up- "many" Window: Composition Dwelling "1" *-up- "many" Door: Composition skinparam componentStyle uml2 class Car { .. Field Examples .. - Name: Type { arg1, arg2, argn } +Name: Type { arg1, arg2, argn } #Name: Type { arg1, arg2, argn } ~Name: Type { arg1, arg2, argn } .. Method Examples .. -Name(): Type { arg1, arg2, argn } +Name(): Type { arg1, arg2, argn } #Name(): Type { arg1, arg2, argn } ~Name(): Type { arg1, arg2, argn } .. Static Example .. +{static} Name(): Type { arg1, arg2, argn } .. Abstract Example .. +{abstract} Name(): Type { arg1, arg2, argn } } class Car ICar ()- Car ICar2 ()-- Car Car -() ICar3 +++
Enter fullscreen mode Exit fullscreen mode

Clases

[plantuml] ++++ title Parallel - Activity Diagram start :Eat Hot Wings; :Drink Homebrew; if (Turn On The Game?) then (yes) fork :__Having Fun__!!!; fork again :Scream At TV!!; end fork else (no) :Not Having Fun; :Eat Poptart; endif :Go To Bed; stop +++
Enter fullscreen mode Exit fullscreen mode

Activiy Parallel

[plantuml] ++++ title Conditional - Activity Diagram start :Eat Hot Wings; note right: This is a note to the right :Drink Homebrew; note left: This is a note to the left if (Turn On The Game?) then (yes) :__Having Fun__!!!; else (no) :Not Having Fun; endif :Go To Bed; stop +++
Enter fullscreen mode Exit fullscreen mode

Activiy Conditional

[mermaid] ++++ classDiagram Animal <|-- Duck Animal <|-- Fish Animal <|-- Zebra Animal : +int age Animal : +String gender Animal: +isMammal() Animal: +mate() class Duck{ +String beakColor +swim() +quack() } class Fish{ -int sizeInFeet -canEat() } class Zebra{ +bool is_wild +run() } ++++
Enter fullscreen mode Exit fullscreen mode

Clases con Mermaid

Arquitectura 

[plantuml] ++++ !define SPRITESURL https://raw.githubusercontent.com/rabelenda/cicon-plantuml-sprites/v1.0/sprites !includeurl SPRITESURL/tomcat.puml !includeurl SPRITESURL/kafka.puml !includeurl SPRITESURL/java.puml !includeurl SPRITESURL/cassandra.puml !includeurl SPRITESURL/python.puml !includeurl SPRITESURL/redis.puml title Cloudinsight sprites example skinparam monochrome true rectangle "<$tomcat>\nwebapp" as webapp queue "<$kafka>" as kafka rectangle "<$java>\ndaemon" as daemon rectangle "<$python>\ndaemon2" as daemon2 database "<$cassandra>" as cassandra database "<$redis>" as redis webapp -> kafka kafka -> daemon kafka -> daemon2 daemon --> cassandra daemon2 --> redis ++++
Enter fullscreen mode Exit fullscreen mode

Arquitectura software

Gestion proyectos 

[mermaid] ++++ gantt title A Gantt Diagram dateFormat YYYY-MM-DD section Section A task :a1, 2014-01-01, 30d Another task :after a1 , 20d section Another Task in sec :2014-01-12 , 12d another task : 24d ++++
Enter fullscreen mode Exit fullscreen mode

Grant

UI/UX 

[plantuml] ++++ @startsalt { Just plain text [This is my button] () Unchecked radio (X) Checked radio [] Unchecked box [X] Checked box "This is a textbox " ^This is a droplist^ == User Name:| "Justin " Password: | "**** " [Ok ] | [ Close ] == Name | " " Direction: | { (X) Left | () Right | () Up | () Down } Attending?: | { [] Yes | [] No [] Maybe } [Browse...] } } @endsalt +++
Enter fullscreen mode Exit fullscreen mode

UI

[plantuml] ++++ @startsalt {+ {/ <b>General | Fullscreen | Behavior | Saving } { { Open image in: | ^Smart Mode^ } [X] Smooth images when zoomed [X] Confirm image deletion [ ] Show hidden images } [Close] } @ensalt ++++
Enter fullscreen mode Exit fullscreen mode

UI

[plantuml] ++++ (*) --> " {{ salt {+ <b>an example choose one option ()one ()two [ok] } }} " as choose choose -right-> " {{ salt {+ <b>please wait operation in progress <&clock> [cancel] } }} " as wait wait -right-> " {{ salt {+ <b>success congratulations! [ok] } }} " as success wait -down-> " {{ salt {+ <b>error failed, sorry [ok] } }} " ++++
Enter fullscreen mode Exit fullscreen mode

UX

Sintaxis 

[syntrax] ++++ stack( line('attribute', '/(attribute) identifier', 'of'), line(choice(toploop('/entity_designator', ','), 'others', 'all'), ':'), opt('bypass'), line(optx('A', 'B', 'C')), line('/entity_class', 'is', '/expression', ';') ) ++++
Enter fullscreen mode Exit fullscreen mode

Railroad

Otros

Source Tabla periódica

Tabla periodica

Top comments (0)