Aller au contenu

Figures

La macro {{ figure() }} permet d'insérer une balise div en spécifiant son identifiant html, pour ensuite y afficher :

  • Des figures dessinées avec matplotlib).
  • Des graphes mermaid.
  • ... Ou toute autre chose qui aurait besoin d'être inséré dans une balise de la page durant les exécutions de codes python.

Signature#

{{ figure(
    div_id:     str = 'figure1',
    *,
    div_class:  str = '',
    inner_text: str = 'Votre tracé sera ici',
    admo_kind:  str = '!!!',
    admo_class: str = 'tip',
    admo_title: str = 'Votre figure',
    p5_buttons: str = None,
    SHOW:       str = '',
) }}


L'astérisque seule dans figure(..., *, ...) ?

Cette astérisque fait qu'il n'est pas possible d'utiliser les arguments autres que div_id sans renseigner le nom de l'argument en plus de la valeur. Tous les arguments suivant sont donc arguments nommés.

Nota: div_id est un argument positionnel avec valeur par défaut, et non un argument nommé.


Exemples :

Syntaxe :#

{{ figure() }}

Résultat :#

Votre figure

Votre tracé sera ici

Syntaxe :#

{{ figure(
    "figure3", 
    div_class = "py_mk_figure orange", 
    admo_kind = "???", 
    admo_title = "Repliée...", 
    inner_text = "_Here!<br>(Note: la classe `orange`{.orange} ne provient pas du thème mais de la documentation elle-même)_", 
) }}

Résultat :#

Repliée...

Here!
(Note: la classe orange ne provient pas du thème mais de la documentation elle-même)

Syntaxe :#

{{ figure(
    "figure2", 
    div_class="py_mk_figure pmt-border", 
    admo_kind="",
    inner_text = "_Note: la classe `pmt-border` ne provient pas du thème, mais de la documentation elle-même._",
) }}

Résultat :#

Note: la classe pmt-border ne provient pas du thème, mais de la documentation elle-même.

Arguments#

Argument Type/défaut Rôle
div_id 'figure1' Id html de la div qui accueillera la figure ou l'élément inséré dynamiquement.
À modifier s'il y a plusieurs figures insérées dans la même page.
div_class '' Classe html à ajouter à la div qui accueillera la figure.
La classe py_mk_figure est systématiquement présente : il possible de surcharger les règles css de cette classe pour obtenir l'affichage voulu.
inner_text 'Votre tracé sera ici' Texte qui sera affiché avant qu'une figure ne soit tracée.
admo_kind '!!!' Type d'admonition dans laquelle la figure sera affichée ('???' et '???+' sont également utilisables).
Si admo_kind est '', la <div> sera ajoutée sans admonition, et les arguments suivants seront alors ignorés.
admo_class 'tip' Pour changer la classe d'admonition. Il est également possible d'ajouter d'autres classes si besoin, en les séparant par des espaces (exemple : 'tip inline end my-class').
admo_title 'Votre figure' Pour changer le titre de l'admonition.
p5_buttons str Si défini, ajoute les boutons start/step/stop pour gérer les animations construites avec p5.
Les boutons sont ajoutés sur le côté indiqué du canevas, les valeurs possibles étant "left", "right", "top" et "bottom".
SHOW '' Affiche des données sur l'appel de macro dans le terminal, durant le mkdocs serve :
  • '': Ne fait rien (défaut).
  • 'args': Affiche tous les arguments de l'appel de macro.


Modifier les valeurs par défaut des arguments

La configuration du plugin pyodide_macros comporte, outre les réglages du plugin lui-même, les valeurs par défaut pour la quasi totalité des macros proposées par le thème.

Ces réglages peuvent être modifiés de différentes façons pour affecter un fichier, un dossier ou une hiérarchie de dossiers :

  1. Via le fichier mkdocs.yml du thème, bien sûr (dans la section plugins.pyodide_macros).
  2. Via des fichiers .meta.pmt.yml, qui peuvent être placés n'importe où dans la hiérarchie de la documentation et qui affectent tous les fichiers "descendants".
  3. Via les métadonnées placées dans les entêtes des pages markdown elles-mêmes.

Personnalisations#

Formatage css de la div#

La classe html .py_mk_figure est définie par le thème et gère le formatage par défaut des balises div qui accueillent les figures.

Il est possible de surcharger cette règle dans un fichier .css ajouté dans docs et référencé dans le fichier mkdocs.yml, dans la section extra_css.

Il est également possible de changer la classe, ou d'en ajouter d'autres via l'argument div_class.

Plusieurs figures dans la page#

Si la même page de documentation doit intégrer plusieurs figures, il est indispensable de renseigner l'argument div_id de la macro figure, en renseignant à chaque fois un nouvel identifiant. Sans cela, tous les graphiques seront dessinés dans la première div.