Généralités concernant le runtime et l'environnement#

Cette page donne des informations sur les macros disponibles avec le thème, leurs réglages et le fonctionnement de l'environnement lui-même.

Résumé des macros disponibles#

IDEIDEvterminalpy_btnrunsectionpymulti_qcmfigure

Création d'un IDE comportant :

Un éditeur de code ( ++ctrl+,++ ou F1 pour l'aide et les options, Ctrl+Space pour une autocompletion rudimentaire)
Un terminal (auto-complétion avec Tab, et rappel de l'historique avec ++ctrl+R++ )
Les boutons permettant d'activer les fonctionnalités de cet IDE

Voir la page dédiée aux IDEs pour des explications détaillées.

Syntaxe :#

{{ IDE('exo_mod3') }}

Résultat :#

Évaluations restantes : 5/5

.128013ecqb)%t hwkfdvymgp2lauoCn/(=rPS3;1is:050n0b0h0v0J0u0K0i0c0u0v0K0K0C010h0J0s010406050K0w0q0q0v0D0p040F0x0u0w0$0x0z050A0-0/0;0?0+0s0405160 190A160+0n0J0o0U0W0Y0!0j0J0r0j0u1n0j0h0)050P0e0u0b1i0X0Z011m1o1q1o0h1w1y1u0h0D170h0j0U0_0K0s0v0z0!0t011A1k010m0R0b0z0v0q0b1u1T1V1!1C1%1y1*1,0)0a0i0E0D0x0s0x0K0J0|0z0i0N1R0D0D0b0c240 1/0z170A1P2h1M1O1N1v0n1;0!1q0z1)211u1f1h0V1B2r0J2t0z0x2x1u0s2a172f2h2L0,1U252z1#2E0D0:0u0)0I2e2P0*2O1:2R1C2T2V0)0t2Z1V2#2f2q012*0v2W040G2.2g1a2J0 2x2k0n1O2p2(0!0c2F1-1731182 2N102!05380N2K2P2=0l0)0N0m2|040i2$2Q1j2)0m0)0q2F2{3g2/3v2=0(040B3s3G362?0)0~3E2}2;3N3I0f0L3s0+3T3x0!0k0)0i3)3u3R3l2%3#010K0n0)020d0w0x0h0H3@3_3{3}3`0H0i0y0x292b240i403 3^414a0H3Y3*3u3!2A013o042a0h0w0D3Q2L4i3m3N0z3P3L4j1#0x0)0g4z4v3/0q0J0)3D2L0+0A3j0b2h2I4Q301g322k2n2i0v1x4T0A314N0N0P0R0K04.

Arguments

Voir la page dédiée aux IDEs pour le détail des options ou leurs valeurs par défaut.
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`	`''`	Chemin relatif (sans l'extension du fichier) vers le fichier `{exo}.py` et les éventuels autres fichiers annexes, sur lesquels baser l'IDE. (plus d'informations)
`ID`	`int`	À utiliser pour différencier deux IDEs utilisant les mêmes fichiers annexes, afin de différencier leurs sauvegardes (nota: $ID \ge 0$). (plus d'informations)
`SANS`	`''`	Pour interdire des fonctions builtins, des modules, des accès d'attributs ou de méthodes, ou des mots clefs : chaîne de noms séparés par des virgules et/ou espaces. Les mots clefs viennent en dernier, après le séparateur `AST:`. (plus d'informations)
`WHITE`	`''`	("White list") Ensemble de noms de modules/packages à pré-importer avant que les interdictions ne soient mises en place (voir argument `SANS`. L'argument `WHITE` est normalement obsolète). (plus d'informations)
`REC_LIMIT`	`-1`	Pour imposer une profondeur de récursion maximale. Nota: ne jamais descendre en-dessous de 20. La valeur par défaut, `-1`, signifie que l'argument n'est pas utilisé. (plus d'informations)
`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)
`AUTO_RUN`	`False`	Lance automatiquement le code après avoir affiché la page (lance uniquement les tests publics). (plus d'informations)
`MAX`	`5`	Nombre maximal d'essais de validation avant de rendre la correction et/ou les remarques disponibles. (plus d'informations)
`LOGS`	`True`	Durant des tests de validation, si LOGS est `True`, le code complet d'une assertion est utilisé comme message d'erreur, quand l'assertion a été écrite sans message. (plus d'informations)
`MODE`	`str`	Change le mode d'exécution des codes python. Les modes disponibles sont : `None` : exécutions normales. `'delayed_reveal'` : pour des IDEs n'ayant pas de tests (pas de section `tests` ni `secrets`) mais dont on ne veut pas que la solution s'affiche dès la première exécution (typiquement, des exercices turtle ou p5). Chaque validation fait décroître le nombre d'essais et les solutions et remarques, si elles existent, sont révélées une fois tous les essais consommés (une erreur est levée durant le build, si l'IDE a des sections `tests` ou `secrets`, ou s'il a un nombre d'essais infini). `'no_reveal'` : exécutions normales, mais les solutions et remarques, si elles existent, ne sont jamais révélées, même en cas de succès. Le compteur d'essais est $\infty$. `'no_valid'` : quels que soient les fichiers/sections disponibles, le bouton et les raccourcis de validations sont inactifs. Le compteur d'essais est $\infty$. `'revealed'` : les solutions et remarques, si elles existent, sont révélées dès le chargement de la page. Le compteur d'essais est $\infty$. (plus d'informations)
`MIN_SIZE`	`3`	Nombre de lignes minimal de l'éditeur. (plus d'informations)
`MAX_SIZE`	`30`	Impose la hauteur maximale possible pour un éditeur, en nombres de lignes. (plus d'informations)
`TERM_H`	`10`	Nombre de lignes initiales utilisées pour la hauteur du terminal (approximatif). (plus d'informations)
`TEST`	`''`	Définit la façon dont l'IDE doit être géré lors des tests dans la page générée automatiquement pour tester tous les IDEs de la documentation. Depuis un fichier de configuration, un fichier`.meta.pmt.yml` ou l'entête d'une page markdown : `""`, `"skip"`, `"fail"`, `"code"`, `"human"` et `"no_clear"`. Depuis un appel de macro: les mêmes, ou bien utiliser un object `Case`, défini dans l'environnement, pour plus de possibilités. (plus d'informations)
`TWO_COLS`	`False`	Si `True`, cet IDE passe automatiquement en mode "deux colonnes" au chargement de la page. (plus d'informations)
`STD_KEY`	`''`	Clef à passer en argument de `terminal_message` pour autoriser son utilisation lorsque la sortie standard est désactivée pendant les tests. (plus d'informations)
`EXPORT`	`False`	Définis si le contenu de l'éditeur de cet IDE doit être ajouté à l'archive zip récupérant les codes de tous les IDEs de la page. (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.

Création d'un IDE sur deux colonnes avec :

Un éditeur de code ( ++ctrl+,++ ou F1 pour l'aide et les options, Ctrl+Space pour une autocompletion rudimentaire)
Un terminal (auto-complétion avec Tab, et rappel de l'historique avec ++ctrl+R++ )
Les boutons permettant d'activer les fonctionnalités de cet IDE

Voir la page dédiée aux IDEs pour des explications détaillées.

Syntaxe :#

{{ IDEv(MAX_SIZE=6) }}

Résultat :#

IDEv et panneaux coulissants...

Comme vous l'aurez peut-être constaté avec l'IDEv ci-dessus, il arrive parfois que le terminal reste vide quand on change d'onglet après chargement de la page (idem avec les admonitions initialement repliées).

On peut alors retrouver un état normal du terminal, soit en cliquant dessus, soit en exécutant les codes python associés à l'IDE.

Arguments

Voir la page dédiée aux IDEs pour le détail des options ou leurs valeurs par défaut.
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`	`''`	Chemin relatif (sans l'extension du fichier) vers le fichier `{exo}.py` et les éventuels autres fichiers annexes, sur lesquels baser l'IDE. (plus d'informations)
`ID`	`int`	À utiliser pour différencier deux IDEs utilisant les mêmes fichiers annexes, afin de différencier leurs sauvegardes (nota: $ID \ge 0$). (plus d'informations)
`SANS`	`''`	Pour interdire des fonctions builtins, des modules, des accès d'attributs ou de méthodes, ou des mots clefs : chaîne de noms séparés par des virgules et/ou espaces. Les mots clefs viennent en dernier, après le séparateur `AST:`. (plus d'informations)
`WHITE`	`''`	("White list") Ensemble de noms de modules/packages à pré-importer avant que les interdictions ne soient mises en place (voir argument `SANS`. L'argument `WHITE` est normalement obsolète). (plus d'informations)
`REC_LIMIT`	`-1`	Pour imposer une profondeur de récursion maximale. Nota: ne jamais descendre en-dessous de 20. La valeur par défaut, `-1`, signifie que l'argument n'est pas utilisé. (plus d'informations)
`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)
`AUTO_RUN`	`False`	Lance automatiquement le code après avoir affiché la page (lance uniquement les tests publics). (plus d'informations)
`MAX`	`5`	Nombre maximal d'essais de validation avant de rendre la correction et/ou les remarques disponibles. (plus d'informations)
`LOGS`	`True`	Durant des tests de validation, si LOGS est `True`, le code complet d'une assertion est utilisé comme message d'erreur, quand l'assertion a été écrite sans message. (plus d'informations)
`MODE`	`str`	Change le mode d'exécution des codes python. Les modes disponibles sont : `None` : exécutions normales. `'delayed_reveal'` : pour des IDEs n'ayant pas de tests (pas de section `tests` ni `secrets`) mais dont on ne veut pas que la solution s'affiche dès la première exécution (typiquement, des exercices turtle ou p5). Chaque validation fait décroître le nombre d'essais et les solutions et remarques, si elles existent, sont révélées une fois tous les essais consommés (une erreur est levée durant le build, si l'IDE a des sections `tests` ou `secrets`, ou s'il a un nombre d'essais infini). `'no_reveal'` : exécutions normales, mais les solutions et remarques, si elles existent, ne sont jamais révélées, même en cas de succès. Le compteur d'essais est $\infty$. `'no_valid'` : quels que soient les fichiers/sections disponibles, le bouton et les raccourcis de validations sont inactifs. Le compteur d'essais est $\infty$. `'revealed'` : les solutions et remarques, si elles existent, sont révélées dès le chargement de la page. Le compteur d'essais est $\infty$. (plus d'informations)
`MIN_SIZE`	`3`	Nombre de lignes minimal de l'éditeur. (plus d'informations)
`MAX_SIZE`	`30`	Impose la hauteur maximale possible pour un éditeur, en nombres de lignes. (plus d'informations)
`TERM_H`	`10`	Nombre de lignes initiales utilisées pour la hauteur du terminal (approximatif). (plus d'informations)
`TEST`	`''`	Définit la façon dont l'IDE doit être géré lors des tests dans la page générée automatiquement pour tester tous les IDEs de la documentation. Depuis un fichier de configuration, un fichier`.meta.pmt.yml` ou l'entête d'une page markdown : `""`, `"skip"`, `"fail"`, `"code"`, `"human"` et `"no_clear"`. Depuis un appel de macro: les mêmes, ou bien utiliser un object `Case`, défini dans l'environnement, pour plus de possibilités. (plus d'informations)
`TWO_COLS`	`False`	Si `True`, cet IDE passe automatiquement en mode "deux colonnes" au chargement de la page. (plus d'informations)
`STD_KEY`	`''`	Clef à passer en argument de `terminal_message` pour autoriser son utilisation lorsque la sortie standard est désactivée pendant les tests. (plus d'informations)
`EXPORT`	`False`	Définis si le contenu de l'éditeur de cet IDE doit être ajouté à l'archive zip récupérant les codes de tous les IDEs de la page. (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.

Création d'un terminal isolé, proposant :

Auto-complétion avec Tab
Rappel de l'historique avec Ctrl+R

Voir la page dédiée aux terminaux pour des explications détaillées.

Syntaxe :#

{{ terminal('exo', ...) }}

Résultat :#

Arguments

Voir la page dédiée aux terminaux pour le détail des options ou leurs valeurs par défaut.
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 terminal isolé utilisant le fichier python correspondant (sections autorisées: `env`, `env_term`, `post_term`, `post` 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)
`SANS`	`''`	Pour interdire des fonctions builtins, des modules, des accès d'attributs ou de méthodes, ou des mots clefs : chaîne de noms séparés par des virgules et/ou espaces. Les mots clefs viennent en dernier, après le séparateur `AST:`. (plus d'informations)
`WHITE`	`''`	("White list") Ensemble de noms de modules/packages à pré-importer avant que les interdictions ne soient mises en place (voir argument `SANS`. L'argument `WHITE` est normalement obsolète). (plus d'informations)
`REC_LIMIT`	`-1`	Pour imposer une profondeur de récursion maximale. Nota: ne jamais descendre en-dessous de 20. La valeur par défaut, `-1`, signifie que l'argument n'est pas utilisé. (plus d'informations)
`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)
`AUTO_RUN`	`False`	Lance automatiquement le code après avoir affiché la page. (plus d'informations)
`TERM_H`	`10`	Nombre de lignes initiales utilisées pour la hauteur du terminal (approximatif). (plus d'informations)
`FILL`	`''`	Commande à afficher dans le terminal lors de sa création. Uniquement pour les terminaux isolés.

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.

L'ancien argument SIZE

Une version antérieure du thème proposait un argument SIZE, qui est maintenant remplacé par TERM_H.
L'ancien argument est cependant toujours supporté, et il n'est pas nécessaire de mettre à jour les appels de macros.

{{ py_btn('exo', TIP="Lancer pour faire ci ou ça" ...) }}

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).

Voir la page dédiée aux boutons pour des explications détaillées.

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.

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)
`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.

{{ run('todo') }}

Cette macro est l'équivalent d'un {{ py_btn(..., AUTO_RUN=True) }}, mais sans le bouton visible dans la page.

Elle peut s'avérer utile pour initialiser une animation p5 au chargement de la page, créer un graphique, ...

Voir la page dédiée aux boutons pour des explications détaillées et un exemple d'utilisation.

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`	`''`	Chemin relatif vers le fichier python (sans extension) à exécuter au chargement de la page (section `env` uniquement). (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)
`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.

Insère dans le document en cours la section indiquée de l'exercice, dans un bloc de code.
Utilisable quel que soit le format des fichiers utilisé.

Syntaxe :#

{{ section('exo_mod3', 'corr') }}

Résultat :#

def mod3(n):
    """ Correction """
    return n%3

Contenu de exo_mod3.py

# --- PYODIDE:code --- #

def mod3(n):
    """ do something appropriate... """
    ...

# --- PYODIDE:corr --- #

def mod3(n):
    """ Correction """
    return n%3

# --- PYODIDE:tests --- #

assert mod3(4) == 1, 'mod(4)'
assert mod3(3) == 0, 'mod(3)'
assert mod3(2) == 2, 'mod(2)'

# --- PYODIDE:secrets --- #

assert mod3(3) == 0, 'mod(3)'

Arguments

Argument	Type/défaut	Rôle
`py_name`	`''`	Fichier python annexe. (plus d'informations)
`section`	`str`	Nom de la section à extraire.

Permet l'insertion du code d'un fichier python dans la page.

Si elle est utilisée avec un fichier python respectant le format des anciens fichiers sources utilisés par pyodide-mkdocs, seul l'équivalent de la section code sera inséré.

Fichier .py quelconqueVieux fichier .py

Intègre tout le contenu du fichier à la page :

Syntaxe :#

{{ py('exo_term') }}

Résultat :#

# --- PYODIDE:env --- #
print('...env! (once only)')

# --- PYODIDE:env_term --- #

print('In env_term, with __USER_CMD__ =', __USER_CMD__)

def inf_rec():
    def rec(n):
        if n<50: rec(n+1)
    rec(0)

# --- PYODIDE:post_term --- #
print('In post_term...')
print("Try inf_rec(), sorted()")

# --- PYODIDE:post --- #
print('...post! (once only)')

Contenu de exo_term.py

# --- PYODIDE:env --- #
print('...env! (once only)')

# --- PYODIDE:env_term --- #

print('In env_term, with __USER_CMD__ =', __USER_CMD__)

def inf_rec():
    def rec(n):
        if n<50: rec(n+1)
    rec(0)

# --- PYODIDE:post_term --- #
print('In post_term...')
print("Try inf_rec(), sorted()")

# --- PYODIDE:post --- #
print('...post! (once only)')

Intègre uniquement l'équivalent de la section code des fichiers python utilisés par la thème :

Syntaxe :#

{{ py('exo_mod3_old') }}

Résultat :#

def mod3(n):
    """ do something appropriate... """
    ...

Contenu du fichier exo_mod3_old.py

# --- HDR --- #

# Cette section est supprimée...

# --- HDR --- #

def mod3(n):
    """ do something appropriate... """
    ...

# Tests

assert mod3(4) == 1, 'mod(4)'
assert mod3(3) == 0, 'mod(3)'
assert mod3(2) == 2, 'mod(2)'

Arguments

Argument	Type/défaut	Rôle
`py_name`	`str`	Fichier source à utiliser (sans l'extension).

Permet d'insérer un ensemble de questions à choix multiples (ou uniques), avec différentes fonctionnalités disponibles :

Correction automatique.
Option pour ne pas afficher les réponses correctes lors de la correction.
Option pour mélanger automatique des questions et de leurs items.
...

Voir la page dédiée pour des explications détaillées.

Syntaxe :#

{{ multi_qcm(...) }}

Résultat :#

Exemple fonctionnelLa déclaration exacte

Exemple fonctionnel de QCM avec mélange automatique

On peut utiliser du TeX: $F_n$ | Blabla... (réponses corrects: texte & !!!)
- Là aussi on peut mettre du TeX: $F_{n+1}$
- !!!
- ...
- ...

Choix multiples possibles, mais une seule bonne réponse :super-vilain: (réponse correct: "On peut aussi...")
- Déchiffrer illégitimement le message
- Chiffrer le message
- Dissimuler le message dans un support
- On peut aussi mettre de contenus plus complexes, du moment que...:
  - c'est de la syntaxe markdown valide et que...
  - les niveaux d'indentation...
    - dans le contenu...
    - sont cohérents.
  (Noter que la première ligne vide de cette chaîne de caractère est automatiquement supprimée)

Blabla... (réponse correct: code python)
- Alice a besoin de la clé privée de Bob
- Alice a besoin de la clé publique de Bob
- Bob a besoin de la clé privée d'Alice
- ```
# On peut aussi insérer des blocs de code
def func():
    return 26
```

{{ multi_qcm(
    [
        "On peut utiliser du TeX: $F_n$ | Blabla... (réponses corrects: texte & !!!)",
        [
            "Là aussi on peut mettre du TeX: $F_{n+1}$ ",
            "!!!",
            "...",
            "...",
        ],
        [1,2]
    ],
    [
        "Choix multiples possibles, mais une seule bonne réponse :super-vilain: (réponse correct: \"On peut aussi...\")",
        [
            "Déchiffrer illégitimement le message",
            "Chiffrer le message",
            "Dissimuler le message dans un support",
            """

            On peut aussi mettre de contenus plus complexes, du moment que...:

            * c'est de la syntaxe markdown valide et que...
            * les niveaux d'indentation...
                * dans le contenu...
                * sont cohérents.

            _(Noter que la première ligne vide de cette chaîne de caractère est automatiquement supprimée)_
            """,
        ],
        [4],
        {'multi': True},
    ],
    [
        "Blabla... (réponse correct: code python)",
        [
            "Alice a besoin de la clé privée de Bob",
            "Alice a besoin de la clé publique de Bob",
            "Bob a besoin de la clé privée d'Alice",
            """
            ```python title=''
            # On peut aussi insérer des blocs de code
            def func():
                return 26
            ```
            """,
        ],
        [4]
    ],
    qcm_title = "Exemple fonctionnel de QCM avec mélange automatique",
    multi = False,
    shuffle = True,
) }}

Arguments

Argument	Type/défaut	Rôle
`questions`	`list`	Chaque argument individuel est une liste décrivant une question avec ses choix et réponses. Il est également possible de passer en unique argument un chemin relatif vers un fichier `.json` comportant une configuration complète (ou partielle) pour déclarer un `multi_qcm`.
`description`	`''`	Texte d'introduction (markdown) d'un QCM, ajouté au début de l'admonition, avant la première question. Cet argument est optionnel.
`hide`	`False`	Si `True`, un masque apparaît au-dessus des boutons pour signaler à l'utilisateur que les réponses resteront cachées après validation.
`multi`	`False`	Réglage pour toutes les questions du qcm ayant une seule bonne réponse, indiquant si elles doivent être considérées comme étant à choix simple ou multiples.
`shuffle`	`False`	Mélange les questions et leurs choix ou pas, à chaque fois que le qcm est joué.
`shuffle_questions`	`False`	Mélange les questions uniquement, à chaque fois que le qcm est joué.
`shuffle_items`	`False`	Mélange seulement les items de chaque question, à chaque fois que le qcm est joué.
`admo_kind`	`'!!!'`	Type d'admonition dans laquelle les questions seront rassemblées : `'!!!'` : classique, `'???'` : dépliable, `'???+'` : repliable, `None` : pas d'admonition autour du qcm. `None` permet d'ajouter du contenu markdown autour du qcm de manière plus fine, si besoin. À noter que l'admonition restera visible dans le markdown généré par la macro : elle sera supprimée dans la couche JS, au moment de l'affichage de la page html.
`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'`).
`qcm_title`	`'Question'`	Pour changer le titre de l'admonition.
`tag_list_of_qs`	`str`	`None` : automatique (défaut). `"ol"` : questions numérotées. `"ul"` : questions avec puces. Définit le type de liste html utilisée pour construire les questions. Si la valeur est `None`, '`"ol"` est utilisé, sauf s'il n'y a qu'une seule question pour le qcm, où c'est alors `"ul"` qui est utilisé.
`DEBUG`	`False`	Si `True`, affiche dans la console le code markdown généré pour ce qcm.

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.

Détail de la structure d'un élément (= une question) de l'argument *questions (plus de détails sur cette page.) :

multi_qcm(
    [
        "intitulé de question (du md, possiblement multilignes)",
        ["choix 1", "choix2", ...],
        [1,3],       # numéro des réponses correctes
        # Un dictionnaire optionnel en 4e argument. Couples clef-valeur possible:
        #   {'multi': bool, "shuffle": bool}
    ],
    ...,
)

Voir la page dédiée pour des explications détaillées.

La macro figure permet d'insérer une div avec l'identifiant html indiqué, potentiellement à l'intérieur d'une admonition, pour pouvoir ensuite y afficher des graphiques dessinés durant les exécutions (ex: une figure dessinée avec matplotlib, ou un graphe mermaid).

Syntaxe générale :#

{{ figure('id', ...) }}

Résultats :#

DéfautSans admonitionPersonnalisée

Syntaxe :#

{{ figure() }}

Résultat :#

Votre figure

Votre tracé sera ici

Syntaxe :#

{{ figure("figure2", admo_kind="") }}

Résultat :#

Votre tracé sera ici

Syntaxe :#

{{ figure(
    "figure3", 
    div_class = "py_mk_figure orange", 
    admo_kind = "???", 
    admo_title = "Repliée...", 
    inner_text = "_Here!<br>(Note: the `orange`{.orange} class is not defined in the theme)_",
) }}

Résultat :#

Repliée...

Here!
(Note: the orange class is not defined in the theme)

Autre utilisation possible: turtle dans pyodide

Il est également possible d'utiliser cette macro pour obtenir un élément dans lequel tracer ensuite des dessins avec l'émulateur de turtle pour Pyodide, mis en place par Romain Janvier.

Un tutoriel de son utilisation avec des exemples est disponible ici : turtle dans pyodide (développement: Romain Janvier / tutoriel : Mireille Coilhac)

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`	`'py_mk_figure'`	Classe html à donner à la div qui accueillera la figure. Il est possible d'en changer ou d'en mettre plusieurs, selon les besoins. Il est aussi possible de surcharger les règles css de la classe par défaut, 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"`.

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.

Étendue de l'environnement pyodide#

L'environnement pyodide est commun à l'intégralité des éléments se trouvant dans une page du site.

Cela présente l'avantage de pouvoir séparer des exercices complexes dans plusieurs IDE ou terminaux, à l'image de ce qui peut se faire avec un notebook Jupyter.

Il faut cependant garder en tête les points suivants :

Si l'un des IDEs comporte des restrictions (fonctions interdites, ...), tous les IDEs et terminaux de la page doivent contenir ces mêmes restrictions (les réglages via les entêtes markdown peuvent être mis à profit pour cela).
Si une tâche est répartie sur plusieurs IDE, ils doivent tous être complétés et exécutés dans le bon ordre pour que tout se passe bien (responsabilité de l'utilisateur).
Il est possible de mettre à profit les sections env des IDE pour faire en sorte que chaque IDE dispose de tout le nécessaire pour fonctionner indépendamment des autres. Garder cependant en tête que dans ce cas, un utilisateur ne lançant pas les IDE dans l'ordre peut se retrouver à ne plus avoir besoin de coder ses propres fonctions si les premiers IDEs ne font pas eux aussi le ménage en supprimant ce qui n'est pas sensé être défini (La tâche devient rapidement fastidieuse pour le rédacteur, cependant...).

Réglages/arguments globaux#

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.

Ceci peut grandement faciliter la déclaration des macros avec des réglages semi-globaux, pouvant être appliqués à toutes les macros d'un fichier, ou toutes celles d'un dossier ou d'une hiérarchie de sous-dossiers.

Plus d'informations sur les configurations semi-globales ici.

Documenter des macros ou du code Jinja#

Si vous souhaitez inclure dans votre documentation des éléments utilisant les syntaxes des macros ou créer un cours sur les syntaxes jinja, il vous faudra placer le code en question entre des balises {% raw %} ... {% endraw %}, afin qu'il ne soit pas considéré comme du code exécutable, ni par le plugin des macros, ni par le moteur Jinja.

Exemple

Avec balises raw :

{% raw %}
{% set running=True %}
{% if running %} Ce contenu est exécutable.
{% else %} Ce contenu n'est pas est exécutable.
{% endif %}
{% endraw %}

Le même code, mais sans les balises raw autour :
```
 Ce contenu est exécutable.
```