PlantUML
PlantUML est un outil open-source qui permet de créer des diagrammes à partir d’une description textuelle. Il permet de créer des diagrammes UML, comme son nom l’indique, mais aussi des diagrammes d’autres langages de modélisation, comme Archimate,BPMN, C4, Computer Network Diagram, Entité-Association, Diagramme de Gantt, Carte Heuristique et Organigramme des Tâches de Projet.
Le langage de description de diagrammes est un langage dédié, ou Domain Specific Language, DSL en anglais. Il utilise Graphviz pour mettre en page ses diagrammes et Tikz pour le support LaTeX. Les images générées sont aux formats PNG, SVG, LaTeX ou ASCII.
|
PlantUML est un super outil, très simple et facile à utiliser, MAIS ses développeurs n’ont aucune connaissance de la norme UML ! La plupart des exemples du site platuml.com sont syntaxiquement faux. Alors, ne vous basez pas sur leurs exemples ! Allez plutôt sur le site UML Diagrams, dont les exemples sont fidèles à la norme UML. |
1. Premiers pas avec PlantUML
Nous allons commencer par utiliser la version web de PlantUML. Rendez-vous sur un des sites suivants :
1.1. Choisir le type de diagramme
PlantUML supporte différentes sortes de diagrammes, comme nous avons mentionné ci-dessus.
La première et la dernière ligne d’une description PlantUML indiquent au moteur PlantUML quel type de diagramme on souhaite créer.
Par exemple, si la description commence par @startmindmap et se terminer par @endmindmap,
le contenu décrit une carte heuristique.
Il est intéressant de noter que lors qu’on décrit un diagramme UML,
il n’y a pas besoin de spécifier le type de diagramme décrit.[1]
Il suffit de le commencer par @startuml et PlantUML déduira automatiquement le type de diagramme.
Par contre, si vous mélangez des balises incompatibles (où par exemple une section indique un diagramme de séquence, mais l’autre indique un diagramme de déploiement), PlantUML peut indiquer une erreur de syntaxe.
1.2. La syntaxe PlantUML
Pour commencer, le plus simple est d’apprendre la syntaxe par l’exemple. Choisissez le type de diagramme que vous voulez construire, puis regardez les douzaines d’exemples de la documentation officielle pour le type de diagramme spécifique sur lequel vous souhaitez travailler.
Si vous ne cherchez pas à créer un type de diagramme spécifique, mais souhaitez simplement construire un diagramme avec quelques boîtes et des lignes de connexion, utilisez le diagramme de déploiement. Il dispose de plusieurs formes de boîtes et permettent également d’imbriquer des boîtes les unes dans les autres
Enb regardant les exemples, vous constaterez que souvent, il existe plusieurs alternatives pour le balisage. Il existe un code plus court et plus concis, qui est moins compréhensible pour les nouveaux arrivants, et des alternatives plus verbeuses. L’exemple d’un diagramme de cas d’utilisation en est la meilleure illustration. L’exemple suivant montre deux extraits de code qui produisent exactement le même diagramme:
@startuml
actor "Professeur" as prof
actor "Étudiant" as etudiant
usecase "Enseigne" as enseigne
usecase "Evalue" as evalue
usecase "Fait des devoirs" as devoirs
usecase "QCM" as qcm
prof - enseigne
prof - evalue
enseigne - etudiant
evalue - etudiant
devoirs - etudiant
evalue <-[dashed]- qcm : extends
@endumlCe premier extrait montre la description d’un diagramme de cas d’utilisation.
Les premières lignes définissent les éléments (de type actor et usecase),
les dernières lignes définissent les liens entre eux.
Notez qu’un élément peut avoir un libellé et un identifiant.
Par exemple, le premier acteur a pour libellé "Professeur" et comme identifiant prof.
Le libellé peut contenir (presque) n’importe quel caractère entre guillemets. L’identifiant est plus contraint, il ne peut pas contenir des espaces ni des caractères accentués.
@startuml
Professeur - (enseigne)
Professeur - (evalue)
(enseigne) - Etudiant
(evalue) - Etudiant
(Fait des devoirs) - Etudiant
(evalue) <.. (QCM) : extends
@endumlLa compréhension de la syntaxe de ce deuxième extrait de code est plus difficile, car il contient quelques raccourcis :
-
Les identifiants simples sont considérés comme des Acteurs.
-
Les cas d’utilisation sont identifiées grâce aux parenthèses.
-
L’existence d’acteurs et de cas d’utilisation indiquent implicitement à PlantUML qu’il s’agit d’un diagramme de cas d’utilisation.
-
Ni les cas d’utilisation ni les acteurs ne sont explicitement définis. Chaque fois qu’un lien est défini et que PlantUML ne connaît pas encore l’objet source ou l’objet cible, il crée les éléments manquants automatiquement.
-
Les éléments
ProfesseuretEtudiantn’ont pas type déclaré, mais sont bien reconnus car PlantUML est déjà en mode "cas d’utilisation". Par défaut, il suppose que les éléments sans déclaration de type sont des acteurs. -
En ce qui concerne les connexions, il y a beaucoup de signification implicite derrière les caractères point et tiret qui définissent le type et la longueur de la ligne. Plus vous définissez de caractères (par exemple,
x ….>y vs. ` x ..> y`), plus la connexion sera longue. -
En ce qui concerne le type de ligne, il existe des lignes pleines (
-), des lignes en pointillés (.) et des lignes discontinues (~). Ce n’est pas vraiment intuitif, il faut l’apprendre par cœur. -
Les éléments ne sont pas considérés comme des variables (comme dans le premier exemple), ce qui est une mauvaise pratique car cela rend la maintenance plus difficile.
Dans les deux cas, le résultat sera le même.
Il est possible de définir quelques éléments communs qui sont généralement utiles dans tout diagramme, tels que :
-
Un titre affiché en haut au centre du diagramme
-
Une légende affichée au centre en bas du diagramme
-
Une section d’en-tête ou de pied de page affichée au-dessus (ou au-dessous) de tous les autres éléments (y compris le titre)
-
Une légende qui explique les éléments ou les couleurs de votre diagramme.
@startuml
title Mon premier titre de diagramme
caption Mon premier sous-titre
header
Mon premier en-tête
endheader
legend
Ma légende
endlegend
Professeur - (enseigne)
@endumlCette représentations sera affichée comme suit.
2. Décrire des diagrammes UML en PlantUML
À vous de travailler !
|
2.1. Diagramme de classes
2.2. Diagramme d’objets
| Pour souligner les mots en PlantUML, utilisez le langage Creole. |
3. Afficher des diagrammes PlantUML dans Antora
Pour activer PlantUML dans Antora,
il faut déclarer l’extension asciidoctor-plantuml dans le playbook
et configurer l’attribut contenant l’adresse du serveur, plantuml-server-url.
asciidoc:
extensions:
- asciidoctor-plantuml
attributes:
plantuml-server-url: http://www.plantuml.com/plantuml
|
3.1. Décrire des diagrammes PlantUML dans Asciidoc
Pour décrire et générer des diagrammes PlantUML avec Antora,
utilisez un bloc délimité par ---- et ajoutez à ce bloc le style plantuml.
[plantuml,,svg]
....
class A {
id : Integer
}
....
|
3.2. Inclure des diagrammes PlantUML dans Antora
En Antora, les diagrammes PlantUML doivent être placés dans un dossier appelé examples,
qui doit être au même niveau que le dossier pages.
📄 antora.yml
📂 modules
📂 ROOT
📂 examples
📄 class-diagram.puml
📂 pages
📄 index.adoc
📄 design.adocPour inclure un diagramme PlantUML décrit dans un fichier séparé,
utilisez la directive include dans le fichier Asciidoc.
[plantuml,,svg]
....
include::example$class-diagram.puml[]
....
|