Faire des diagrammes dans un tuto : que faire sur zds

Ces derniers temps, je reprends un peu de motivations pour participer techniquement à ZDS. Et un sujet me plaît particulièrement : intégrer la possibilité de faire des diagrammes avec ZDS.

Des diagrammes il en existe des tonnes très connus :

  • diagramme de flux (pour expliquer un algorithme ou même un processus comme un processus législatif par exemple)
  • diagramme de classe (pour la programmation)
  • diagramme de gantt (pour faire de la gestion de projet)
Problématique

Comment intégrer à zds la possibilité de créer un diagramme pour ensuite le rendre partout de la même manière tant sur le site web que dans nos PDF?

Il existe probablement des milliers de manières de répondre à cette problématique, mais pour ce billet, je vais me concentrer sur une technique qui est particulièrement adaptée à zds : on écrit le diagramme avec une sorte de pseudo code plus ou moins simple dans le tuto lui-même et ZDS se charge de le transformer en une belle image.

Et vous allez voir que ça va être bien plus compliqué à réaliser qu’à exprimer :).

Mermaid JS : tout demander aux navigateurs

Heureusement pour nous, nous ne sommes pas les premiers à penser à ce genre de solutions. Dans le monde du JavaScript, a été développé Mermaid JS qui se présente comme "Une syntaxe à la Markdown pour faire des diagrammes".

Présentation

Ce logiciel, initié par Knut Sveidqvist vous permet de coder 7 "types" de diagrammes :

  • Des diagrammes de flux
  • Des diagrammes de séquence
  • Des diagrammes de classe
  • Des diagrammes d’état
  • Des diagrammes de Gantt
  • Des diagrammes Entité/Relation
  • Des graphiques en camembert

Vous entrez un texte dans une div qui a la classe mermaid et le script va vous traduire ça en image vectorielle : vous pouvez donc zoomer à l’infini sur un diagramme (et c’est parfois très utile).

Par exemple :

graph TD
  A[Christmas] --Get money--> B(Go shopping)
  B --> C{Let me think}
  C -->|One| D[Laptop]
  C -->|Two| E[iPhone]
  C -->|Three| F[fa:fa-car Car]
Crée un diagramme qui en partant de l’idée que c’est Noël cous donne les marche à suivre pour vous acheter un cadeau.

Génère cette image vectorielle :

Un diagramme de flux pour faire des achats de Noel
Un diagramme de flux pour faire des achats de Noel

Le tout vient avec un système de thème qui permet de personnaliser l’affichage global des diagrammes.

Intégration à ZDS?

Comment pourrions-nous intégrer mermaid à ZDS?

La méthode la plus simple consiste à proposer aux gens d’écrire le code que j’ai proposé juste au dessus en utilisant la syntaxe markdown pour ajouter un code, ainsi nous aurions :

```mermaid
graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]
```

Ensuite, techniquement parlant, nous aurions à dire à zMarkdown que les code dont le langage est "mermaid" doivent juste être mis tels-quels dans un div. Puis du côté de zds-site, ajouter le CSS et le code de mermaid.

Cela nous pose deux soucis :

  • L’interprétation du code pour le transformer en diagramme est potentiellement longue. Certains se souviennent peut être de l’époque où nos tutos de science passaient leur temps à faire des allers/retours sur le scroll à cause de l’interprétation des maths par Mathjax. On aurait le même soucis ici. Chaque graphique prend 1 à 10 secondes pour être transformé (j’utilise personnellement mermaid pour faire des graphes au boulot).
  • Comment faire pour avoir l’image générée en latex et ensuite dans notre PDF? (accessoirement le soucis serait identique dans le ebook)?

En effet mermaid a un besoin absolu d’avoir un navigateur pour fonctionner.

La seule possibilité qui existe alors pour faire un rendu "côté serveur" est d’utiliser un navigateur headless pour que notre serveur puisse générer l’image.

Seulement ces outils sont souvent soit marqués comme outil de test (donc peu adaptés à la production) soit très gourmands en ressources et demandent d’avoir une interface graphique virtuelle telle que X-Virtual Frame Buffer(xvfb) pour fonctionner. En somme c’est techniquement possible mais il faut être très prudent avec ce qu’on fait.

Une autre solution serait de passer par un langage intermédiaire qui lui serait adapté au rendu côté serveur mais n’aurait pas besoin de navigateur. On y reviendra plus tard car d’autres considérations nous intéressent pour l’instant.

Yet another language

Venir rédiger sur ZDS c’est apprendre à utiliser markdown, et surtout le markdown sauce ZDS avec ses extensions pour les acronymes, les tableaux, les légendes, les blocs spéciaux…

Ajouter la possibilité de faire des diagrammes par texte, c’est demander d’apprendre un autre langage en plus du markdown. Cela pose quelques questions d’un point de vue utilisabilité :

  • Comment présenter ça aux gens dans notre interface? Comment faire une aide qui soit utilisable? Comme beaucoup d’outils techniques, mermaid a une documentation en anglais. Seul son live editor permet d’ajouter un peu d’aide. En terme de réflexion, cela peut être intéressant, comme ce dernier est open source on peut imaginer que notre éditeur ouvre une "fenêtre d’édition" qui lance une instance du live editor puis, grâce aux nouveautés du JS modernes on pourrait proposer d’insérer le code pré-généré dans le tuto. Mais cela demande quand même aux futurs auteurs de coder avec un nouveau langage.
  • Comment assurer l’accessibilité du diagramme? Est-ce que nos légendes style Code: ma légende seront-elle suffisante pour rendre le diagramme généré accessible?
  • Autre chose?

Une alternative : graphviz

Dans la liste des outils déjà existant on trouve aussi graphviz qui se présente comme un outil de positionnement et rendu des graphes.

Il est mille fois plus connu que mermaid, mais son expression est beaucou, beaucoup, plus difficile. Et pour cause : il s’agit d’organiser des graphes qui seront rendus par un moteur laissé libre (voir le tutoriel sur VisNetwork qui se base sur graphviz pour définir ses graphes). Le langage (nommé Dot) sur lequel il se base ne permet de définir que des graphes "simples" et "dirigés". A vous de voir si votre graphe sera plutôt un diagramme de flux ou d’état une fois rendu.

Prenons par exemple un diagramme qui ressemble énormément au diagramme de flux de tout à l’heure :

Diagramme de flux avec GraphViz
Diagramme de flux avec GraphViz

Outre que le résultat est moins beau, pour le réaliser il aura fallu que je fasse un code beaucoup plus complexe :

digraph test {
    rankdir="TD"
    splines=polyline
    node[style=filled, fillcolor="#ECECFF", color="#9370DB"]
    edge[labelangle=90, labeldistance=2.5, arrowhead="open"]
    A[label=Christmas, shape=rect];
    B[shape=rectangle, label="Go shopping", style="rounded,filled"];
    C[shape=diamond, label="Let me think", height="1em"];
    D[shape=rect, label="laptop"];
    E[shape=rectangle, label="iphone"];
    F[shape=rect, label="Car"];
    A -> B [label="Get money", labelangle=20, labeldistance=2.5]
    B -> C
    C -> D[label="One"]
    C ->E[label="Two"]
    C ->F[label="Three", K=30]

}
code pour générer le graphe du dessus

Bien sûr, ici je peux sélectionner mon "moteur de rendu" et render-dot permet de faire un rendu en SVG (vectoriel) ou PNG côté serveur sans aucun besoin de navigateur headless.

Une hypothèse de travail pourrait donc être de transformer les diagrammes mermaid en dot pour ensuite les rendre.

Le principal problème c’est qu’a priori, tous les diagrammes supportés par mermaid ne sont pas des graphes donc il sera compliqué de les traduire en Dot. De plus comme vous l’avez remarqué, le rendu n’est pas aussi qualitatif.

Cependant graphviz possède quelques autres avantages :

  • la granularité de la personnalisation est immense : une dizaine de formes de flèche contre 3 sur mermaid, des formes de liens droits, courbes, brisées alors que mermaid définit lui-même (parfois un peu bizarrement) s’il doit faire simplement droit ou brisé)
  • la capacité à mettre deux annotations par flèche (au début et à la fin de la flèche, pour les cardinalités par exemple)
  • La gestion des sous-graphes est aussi plus simple
  • Il possède un éditeur simple en mode GUI : graphviz visual editor

On fait quoi?

Je n’ai pas encore de réponse précise à cette question. Je ne sais pas vraiment qui va utiliser parmi les auteurs la capacité à faire des diagrammes. Et parmi ces diagrammes lesquels seront vraiment utiles.

De même je ne sais pas si finalement intégrer des liens vers ces outils ne serait pas plus simple.

Enfin, je ne sais pas non plus s’il n’y a pas quelqu’un qui a déjà codé quelque chose qui répondrait en tout point à notre besoin.

Je suis ouvert à toutes les suggestions mais aussi à toutes les réflexions. Si vous avez des idées d’intégration, de ce qui est important pour l’expérience utilisateur etc. N’hésitez pas à poster un message dans les commentaires.


14 commentaires

Alors je vais sûrement dire une très grosses bêtise (et probablement la dire très mal en plus vu que j’ai pas le bon vocabulaire), désolé d’avance.

J’avais une question par rapport à ça (dans la partie sur mermaid) :

La seule possibilité qui existe alors pour faire un rendu "côté serveur" est d’utiliser un navigateur headless pour que notre serveur puisse générer l’image.

C’est pas possible de détacher le code de mermaid d’une page web et de l’utiliser comme un simple script js (comme on utiliserait un script python) par exemple qui transformerait une entrée (le code) en une sortie (l’image) sans avoir besoin d’un navigateur (fusse-t-il headless) ?

+0 -0

Ce n’est pas une bêtise, et ça a même été une question qu’on s’est posée pendant quelques temps. Mais c’est l’équipe de développement de mermaid qui a répondu : pour faire son rendu, mermaid délègue une partie des calculs au moteur de layout du navigateur, c’est ça qui permet de décider quelles sont les tailles des éléments, des textes etc. De ce fait impossible de se passer du navigateur. Le fait que je propose un "headless" vient du besoin de l’exécuter sur un serveur qui n’a donc pas (logiquement) d’interface graphique à disposition.

Je suis sceptique sur le fait que le jeu en vaut la chandelle. J’ai l’impression que le coût de développement et maintenance d’une telle solution dépasse largement le gain apporté. Tel que je vois les choses, le seul gain réel serait l’uniformité de tels graphes à travers l’ensemble des contenus du site (et encore, à la condition que les gens s’en servent), ce qui me semble un peu léger… Il y a combien de diagrammes sur l’ensemble des tutos du site ? Est-ce que c’est un problème que leurs styles soient différents étant donné que chaque auteur a déjà des styles d’illustrations différents par ailleurs ?

Je prévoyais de développer une réponse dans les jours à venir (pas beaucoup de temps en ce moment), mais globalement je rejoins @adri1, ça va demander un développement non-négligeable (déjà, tu as du passer un peu de temps à essayer de faire marcher Mermaid, et à prospecter dans les docs) pour un intérêt sans doute moindre parce que :

  1. les fonctionnalités sont généralement assez limitées (maths. & info. globalement) ;
  2. c’est clairement réservé à un public plus ou moins geek ;
  3. c’est à l’opposé complet de l’esprit de simplicité du Markdown.

En l’état, il n’est pas certain qu’une telle fonctionnalité soit acceptée dans ZMarkdown, sauf à justifier un véritable intérêt de l’intégration —- pas un intérêt hypothétique, un intérêt réel.

Je sais que je ne m’en servirais probablement pas quelque que soit la solution pour différentes raisons :

  • le style ne me convient pas, peu importe lequel des deux ;
  • je n’ai pas envie d’apprendre un syntaxe pour ça qui me prendra autant de temps à écrire que sortir un outil pratique et copier-coller l’image depuis mon éditeur favori ;
  • même si j’apprenais le truc, je sens venir à l’avance les trucs par défaut durs à adapter.

Limite avoir une balise texte SVG me serait plus utile pour bénéficier d’image versionnée et avec plein de flexibilité.

Que maths et infos je ne sais pas, ce genre de graphiques peut être très intéressant partout, même si l’exemple ici est un exemple logique, n’importe qui peut avoir besoin de faire un camembert, ou par exemple illustrer une logique d’acteurs. En termes de simplicité de rédaction, mermaid c’est génial. Mais fondamentalement, c’est vrai que ce n’est peut-être pas la peine de trop se prendre la tête sur le développement, surtout si au final la génération d’images n’est pas adaptative.

+1 -0

Alors je faisais partie des gens qui avaient suggéré cette évolution, pour deux raisons :

  1. Parce que quand on doit écrire un graphe et qu’on en fait assez peu, c’est très chiant de trouver un outil de graphe correct (on part du principe que les gens comme moi n’en connaissent pas à priori), faire le graphe, l’exporter en image, intégrer l’image (surtout qu’à l’époque il n’y avait pas le glisser-déposer d’images) (et je passe les surprises à base de transparence foireuse).
  2. surtout parce que ça semblait simple à intégrer : la promesse c’était quand même « ajoutez ça à votre markdown et ça marche »

Si c’est le bordel à intégrer de façon propre, alors pour moi il ne faut pas le faire. Surtout que autant Mermaid est assez simple à utiliser, autant graphviz devient vite une purge.

Par contre, je pense ça peut être intéressant d’avoir un raccourci accessible quelque part dans l’interface, un truc genre « outils du rédacteur » qui contiendrait (entre autres) un lien vers un outil de graphe depuis lequel on pourrait facilement extraire des images à ajouter dans le tuto.

Je rejoins aussi @adri1. De plus, l’exemple 2 est trop verbeux et pas hyper propre, autant sortir Inkscape. Et l’exemple 1 n’est pas accessible (ne tient pas compte de la taille de police, est illisible dès qu’on change la police).

La possibilité de mettre du vectoriel me semble préférable pour les graphiques.

+0 -0

Ne me lapidez pas svp … Mais c’est pas plus simple de tout refaire à 0 plutôt que d’essayer d’intégrer une librairie tierces ou d’utiliser un service tiers… Certes ça ne respecte pas le principe DRY mais au moins vous aurez un projet greenfield où vous pourrez adapter à vos besoins spécifiques (ex. utiliser une syntaxe moins verbeuse et anglo-saxonne etc…). Et ainsi ajouter que les fonctionnalités nécessaires à la communauté, que je présume, ne sont pas si nombreuses.

+0 -0

Juste pour dire que maintenant Github a intégré Mermaid, mais ils ont le double avantage de ne pas avoir de génération de fichiers côté serveur et d’avoir un public en écriture exclusivement constitué d’informaticiens ou assimilés.

Peut-être que c’est quelque chose qui relancera le besoin ici… ou peut-être pas.

Connectez-vous pour pouvoir poster un message.
Connexion

Pas encore membre ?

Créez un compte en une minute pour profiter pleinement de toutes les fonctionnalités de Zeste de Savoir. Ici, tout est gratuit et sans publicité.
Créer un compte