DEV Community

Jorge Eψ=Ĥψ
Jorge Eψ=Ĥψ

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)

Read next

nix_25 profile image

AI Infrastructure Essentials: Building a Future-Ready Platform

Nix -

ke1ru profile image

Is it better to integrate AI even though you don't have the good grasp in a framework or language?

Jameson Gelarman -

elvinaspredkelis profile image

Ruby on Rails: Native route constraint for authentication

Elvinas Predkelis -

dhodvogner profile image

<self-close /> or <not-to-self-close></not-to-self-close>

Daniel Hodvogner -