Mermaid

Le thème propose des fonctionnalités pour faciliter l'intégration dans la documentation de graphiques mermaid créés dynamiquement.

Graphes mermaid dans pyodide-mkdocs-theme

Pour pouvoir utiliser des graphes mermaid dans la documentation, il faut dans un premier temps configurer l'extension markdown pymdownx.superfences dans le fichier mkdocs.yml, si cela n'est pas déjà fait :

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Il est alors possible de déclarer des graphes mermaid simplement en déclarant des blocs de code spécifiant mermaid comme langage :

```mermaid
graph TB
    A --- B
```

graph TB
    A --- B

Principe général#

L'idée générale pour que cela fonctionne est la suivante :

Insérer dans le fichier markdown un élément html (une <div>) qui accueillera la figure une fois qu'elle sera créée.
Signifier au thème que la page va devoir gérer du contenu dynamique mermaid (= "marquer la page").
Dans pyodide, préparer une fonction que l'utilisateur pourra appeler pour générer la figure avec mermaid.
Construire les données et appeler la fonction qui va mettre à jour le contenu de la div créée au point 1.

L'étape 1 est facilitée par l'utilisation de la macro {{ figure(...) }}.
L'étape 2 est réalisée en passant MERMAID=True en argument de l'une des macros IDE, IDEv, terminal, py_btn ou run de la page (v. plus bas).
L'étape 3 est facilitée par la fonction mermaid_figure(figure_id), qui renvoie une fonction pour modifier le contenu de la balise div d'identifiant figure_id.
L'utilisateur n'a plus qu'à appeler la fonction avec un code mermaid valide, à l'étape 4.

Exemple simple#

Concrètement, pour un IDE qui devrait générer du code mermaid, puis afficher le graphe correspondant dans la page, les codes markdown et python suivant suffisent pour intégrer une première figure dans la page :

Fichier markdown

Dans la page markdown, on insère:

La balise qui accueillera la figure.
L'IDE qui générera le code mermaid, en n'oubliant pas d'utiliser l'argument MERMAID.

{{ figure() }}

{{ IDE('exemples/mermaid', MERMAID=True) }}

Fichier python

#-PYODIDE:env-#
to_mermaid = mermaid_figure()

#-PYODIDE:code-#
to_mermaid("""
graph TB
    A --- B
""")

La fonction mermaid_figure est définie par le thème. C'est une "function factory", qui crée une fonction qui insèrera le code fourni par l'utilisateur dans la bonne balise html.

Voir plus bas pour plus d'informations sur la fonction mermaid_figure.

Résultat

Votre figure

Votre tracé sera ici

Utilisation dans pyodide#

La fonction `mermaid_figure`#

Cette fonction est similaire aux objets PyodidePlot :

Elle prend un argument optionnel, qui est l'identifiant html (id) de la balise div qui devra accueillir la figure.
Si cet argument n'est pas fourni, c'est la valeur par défaut pour l'argument div_id de la macro figure qui est utilisé.
Tout ceci est compatible avec les configurations via les fichiers .meta.pmt.yml et les entêtes des fichiers markdown.

La fonction mermaid_figure est une "function factory", et renvoie une nouvelle fonction que l'utilisateur pourra appeler pour insérer le graphe mermaid à l'endroit voulu dans la page.
Cette seconde fonction prend deux arguments :

mermaid_figure(id:str) -> (code:str, debug:bool=False) -> None

Argument	Type	Résumé
`code`	`str`	Code du graphe mermaid à insérer.
`debug`	`bool`	[Défaut: `False`] Si l'argument `debug` vaut `True`, le code passé en argument est affiché dans le terminal avant traitement.

Disponibilité de la fonction mermaid_figure

Si elle est toujours définie dans l'environnement, la fonction mermaid_figure lèvera une erreur si la page de la documentation n'a pas été "marquée" comme devant accueillir du contenu mermaid dynamique (argument MERMAID=True).

Cette contrainte permet de garantir que les différents éléments de logique nécessaires sont présents lors des exécutions.

Exécution locale de fichiers python utilisant la fonction mermaid_figure

Méthode 1 :

La "boîte à outil" du thème permet "d'utiliser" la fonction en local. Il suffit de mettre en place le fichier toolbox.py et de l'importer dans le fichier python:

Snippet à ajouter en haut du fichier python

# --- PYODIDE:ignore --- #
from toolbox import *

Méthode 2 :

Il est aussi possible d'ajouter le code suivant au tout début du fichier python de la documentation :

Snippet à ajouter en haut du fichier python

# --- PYODIDE:ignore --- #
mermaid_figure = lambda _: print

Les codes des sections ignore ne sont exécutés qu'en local: ils ne sont pas utilisés pour construire le site final avec mkdocs.

Mise à jour du DOM#

Aucune action de l'utilisateur n'est requise, le thème gère la mise à jour du contenu de la page automatiquement.
Pour information, la mise à jour du DOM est faite en mode async, l'appel se situant après l'exécution des sections post et/ou post_term.

Autres exemples#

Contenu mermaid et macro py_btn

Si tout le code nécessaire est placé dns la section env, une simple macro {{ py_btn(...) }} peut suffire :

md & pyRésultat

{{ figure('btn-fig-id') }}

{{ py_btn('exemples/mermaid_btn', MERMAID=True) }}

#-PYODIDE:env-#
to_mermaid = mermaid_figure('btn-fig-id')

to_mermaid("""
graph TB
    Graph --- with
    Graph --- btn
""")

Votre figure

Votre tracé sera ici

Contenu mermaid et macro terminal

Noter que l'argument MERMAID=True a été ignoré dans cet exemple, car d'autres macros ont déjà été utilisées pour "marquer" cette page.

md & pyRésultat

{{ terminal('exemples/mermaid_term', FILL='generate()', TERM_H=3) }}

{{ figure('term-fig-id') }}

# --- PYODIDE:env --- #
to_mermaid = mermaid_figure('term-fig-id')

def generate():
    to_mermaid("""
graph TB
    Graph --- with
    Graph --- btn
    btn --- from
    btn --- terminal
""")
print('Utiliser: generate()')

Votre figure

Votre tracé sera ici

graph TB
    a

Mermaid

Principe général#

Exemple simple#

Utilisation dans pyodide#

La fonction mermaid_figure#

Mise à jour du DOM#

Autres exemples#

La fonction `mermaid_figure`#