Introducción a Asciidoc y Asciidoctor (5): diagramas
Tags: asciidoc, documentation, write, diagram
Published: 2020-02-24 18:37:42

---
title: Introducción a Asciidoc y Asciidoctor (5): diagramas
published: true
date: 24/02/2020
tags: asciidoc,documentation,write,diagram
canonical_url: https://jorge.aguilera.soy/blog/2020/intro-asciidoctor-5.html
---

| | Este post es la continuación a [intro-asciidoctor-4.html](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.
```

| | 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[]
```

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
```

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](https://jorge.aguilera.soy/images/diag-ce10eaf325fe034a3c9fe082d7ae5d2e.png)

### 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
++++
```

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 |
     +-----------------------------------+
....
```

 ![Ditaa box](https://jorge.aguilera.soy/blog/2020/diagram/ditaa.png)

### 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
+++
```

![Clases](https://jorge.aguilera.soy/blog/2020/diagram/complex.png)

```
[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
+++
```

![Activiy Parallel](https://jorge.aguilera.soy/blog/2020/diagram/parallel.png)

```
[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
+++
```

![Activiy Conditional](https://jorge.aguilera.soy/blog/2020/diagram/conditional.png)

```
[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()
	}
++++
```

![Clases con Mermaid](https://jorge.aguilera.soy/blog/2020/diagram/mermaid.png)

### 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
++++
```

![Arquitectura software](https://jorge.aguilera.soy/blog/2020/diagram/arquitectura.png)

### 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
++++
```

![Grant](https://jorge.aguilera.soy/blog/2020/diagram/grant.png)

### 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
+++
```

 ![UI](https://jorge.aguilera.soy/blog/2020/diagram/salt.png)

```
[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
++++
```

![UI](https://jorge.aguilera.soy/blog/2020/diagram/salt2.png)

```
[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]
}
}}
"
++++
```

![UX](https://jorge.aguilera.soy/blog/2020/diagram/salt3.png)

### 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', ';')
)
++++
```

![Railroad](https://jorge.aguilera.soy/blog/2020/diagram/syntrax1.png)

### Otros

[Source Tabla periódica](https://gitlab.com/snippets/1779830/raw)

 ![Tabla periodica](https://jorge.aguilera.soy/blog/2020/diagram/tablaperiodica.png)