Boutons

Les boutons sont en gros des "IDEs sans éditeur et sans terminal". Ou des terminaux sans terminal...

Ils permettent de lancer un code python arbitraire dans la page (en général, pour utiliser le résultat et modifier le contenu de la page depuis le code python).

Exemples#

Tous les boutons ci-dessous sont actifs, et ne font qu'ouvrir une fenêtre de message du navigateur (window.alert).

Cas	Code markdown	Appel
Défaut	in div	`in div {{ py_btn('py_file') }}`
Span Petit	in text	`in text {{ py_btn('py_file', WRAPPER='span', SIZE=24) }}`
Tip		`{{ py_btn('py_file' TIP="dude!", TIP_SHIFT=5, TIP_WIDTH=20) }}`
Fichier d'icône		`{{ py_btn('py_file', ICON="assets/images/icons8-upload-64.png") }}`
`.icons` (material)		`{{ py_btn('py_file' ICON=":fontawesome-regular-face-laugh-wink:") }}`
`svg`		`{{ py_btn('py_file', SIZE=20, ICON='<svg>...</svg>') }}`
Lien		`{{ py_btn('py_file', ICON="https://codex.forge.apps.education.fr/logo_robot_128x128.png", SIZE=50) }}`

Contenu du fichier py_file.py

# --- PYODIDE:env --- #

from js import window
window.alert('That is me!')

Voir la documentation de Pyodide pour l'utilisation de javascript depuis les codes python.

Signature#

{{ py_btn(
    py_name:     str = '',
    *,
    ID:     None|int = None,
    SHOW:        str = '',
    ICON:        str = '',
    HEIGHT: None|int = None,
    WIDTH:  None|int = None,
    SIZE:   None|int = None,
    TIP:         str = 'Exécuter le code',
    TIP_SHIFT:   int = 50,
    TIP_WIDTH: float = 0.0,
    WRAPPER:     str = 'div',
    MERMAID:    bool = False,
) }}

Arguments#

Tous les arguments sont optionnels.
À part pour le premier, déclarer les arguments en précisant leur nom (donc sous forme d'arguments nommés).

Argument	Type/défaut	Rôle
`py_name`	`''`	Crée un bouton isolé utilisant le fichier python correspondant (uniquement `env` et `ignore`). (plus d'informations)
`ID`	`int`	À utiliser pour différencier deux appels de macros différents, dans le cas où vous tomberiez sur une collision d'id (très improbable, car des hachages sont utilisés. Cet argument ne devrait normalement pas être nécessaire pour cette macro). (plus d'informations)
`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. `'python'`: Affiche les contenus des sections, telles que vues par PMT. `'all'`: Combine `'args'` et `'python'`. (plus d'informations)
`ICON`	`''`	Par défaut, le bouton "play" des tests publics des IDE est utilisé. Peut également être une icône `mkdocs-material`, une adresse vers une image (lien ou fichier), ou du code html. Si un fichier est utiliser, l'adresse doit être relative au `docs_dir` du site construit.
`HEIGHT`	`int`	Hauteur par défaut du bouton.
`WIDTH`	`int`	Largeur par défaut du bouton.
`SIZE`	`int`	Si définie, utilisée pour la largeur et la hauteur du bouton.
`TIP`	`'Exécuter le code'`	Message à utiliser pour l'info-bulle.
`TIP_SHIFT`	`50`	Décalage horizontal de l'info-bulle par rapport au bouton, en `%` (c'est le décalage vers la gauche de l'info-bulle par rapport au point d'ancrage de la flèche au-dessus de celle-ci. `50%` correspond à un centrage).
`TIP_WIDTH`	`0.0`	Largeur de l'info-bulle, en `em` (`0` correspond à une largeur automatique).
`WRAPPER`	`'div'`	Type de balise dans laquelle mettre le bouton.
`MERMAID`	`False`	Signale qu'un rendu de graphe mermaid sera attendu à un moment ou un autre des exécutions. Nota : l'extension markdown `pymdownx.superfences` doit être configurée pour accepter les blocs de code `mermaid`. Voir la configuration par défaut du mkdocs.yml via les scripts du thème, par exemple avec : `python -m pyodide_mkdocs_theme --yml`. (plus d'informations)

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 :

Via le fichier mkdocs.yml du thème, bien sûr (dans la section plugins.pyodide_macros).
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".
Via les métadonnées placées dans les entêtes des pages markdown elles-mêmes.

Voir la page des IDEs concernant la structure des fichiers associés à l'argument py_name.
Seules les sections env et ignore de ces fichiers peuvent être utilisées avec la macro py_btn. Il est rappelé que la section env est exécutée en mode async, ce qui permet plus de souplesse.
Si une autre section ou des fichiers {exo}_REM.md ou {exo}_VIS_REM.md sont trouvés, une erreur est levée.

Un bouton ira en général de paire avec une fonctionnalité pour modifier quelque chose dans la page.
Cette modification peut être faite via le code python, en utilisant les objets proxy proposés par Pyodide, et qui permettent d'interagir avec la couche JS/html de la page. La macro {{ figure() }} peut aussi avoir son utilité ici pour ajouter un élément à la page html qui devra être ensuite modifier par le code : voir par exemple les utilisations avec matplotlib ou mermaid.