IDEs - Guide rapide
But de cette page
Voici une procédure minimale pour utiliser un IDE ou un terminal reposant sur des fichiers python dans une page de la documentation.
Cette page décrit les éléments nécessaire pour les IDEs, mais la procédure est la même pour les terminaux, à quelques détails près.
La page discutant en détail des IDEs, décrit l'intégralité des fonctionnalités disponibles, ainsi que les organisations alternatives des fichiers.
Anciens formats de fichiers utilisés dans pyodide-mkdocs
Les informations données ci-dessous correspondent au mode de travail qu'il serait préférable d'adopter, mais les IDEs restent rétrocompatibles avec les fichiers de pyodide-mkdocs qui utilisait notamment 3 types de fichiers pythons différents ({exo}.py, {exo}_corr.py et {exo}_test.py).
Voir la page de mise à jour depuis pyodide-mkdocs vers le thème pour connaître les changements nécessaires lors de la mise à jour.
Exemple#
Interface & fonctionnalités#
Une description rapide du fonctionnement des IDEs et de leurs fonctionnalités est donnée dans la page d'aide pour les utilisateurs.
Organisation des fichiers #
Pour pouvoir insérer un IDE dans le fichier docs/exercices/est_pair/index.md, l'approche la plus simple est d'organiser les fichiers comme suit :
├── docs
│ ├── exercices
│ │ ├── est_pair
│ │ │ ├── index.md
│ │ │ ├── exo.py
│ │ │ ├── exo_REM.md
│ │ │ └── exo_VIS_REM.md
(Nota: certains fichiers sont optionnels / toute autre hiérarchie est envisageable, seul le contenu du dossier est_pair importe, dans cet exemple)
| Fichier | RĂ´le |
|---|---|
index.md |
Contient l'énoncé de l'exercice et accueil l'IDE. Vous pouvez utiliser un autre nom de fichier si vous voulez. |
{exo}.py |
Contient les différents codes python nécessaires pour l'IDE. Nom de fichier à choisir par vos soins. |
{exo}_REM.md(optionnel) |
Remarques qui seront affichées avec la correction, dans une admonition repliée, lorsque la solution sera révélée.
|
{exo}_VIS_REM.md(optionnel) |
Remarques qui seront affichées après la correction et le fichier REM, en dehors de l'admonition (et donc visibles tout de suite, une fois la solution révélée).
|
Les anciennes organisations des fichiers sont toujours utilisables. Voir à ce sujet la section détaillée concernant les IDEs.
Le fichier index.md#
Placez-y l'énoncé de l'exercice et toutes les informations que vous jugerez utiles, sous forme de syntaxe markdown compatibles avec les extensions et plugins renseignés dans le fichier mkdocs.yml.
Les IDEs y sont ajoutés avec l'appel de la macro IDE, en lui fournissant le nom du fichier python (sans extension) :
[...énoncé, avec tout le markdown qui vous fait envie...]
{{ IDE('exo') }}
Tip
Il existe d'autres façons d'organiser les codes python, en utilisant des fichiers séparés (organisation obsolète, utilisée pour pyodide-mkdocs). Voir la page des détails des IDEs.
Le fichier exo.py#
Contenu#
La structure classique du fichier est celle ci-dessous.
Il est également possible d'afficher ce contenu dans un terminal ou de créer un fichier avec ce contenu en utilisant un des scripts du thème :
python -m pyodide_mkdocs_theme --py
python -m pyodide_mkdocs_theme --py --file "path/exo.py"
Voici donc un exemple de contenu pour un fichier python associé à un IDE :
# --- PYODIDE:ignore --- #
"""
Les sections `ignore` sont... ignorées. Vous pouvez les utiliser pour laisser
des commentaires dans vos fichiers, ou y archiver du code python qui ne sera
pas utilisé pour le site construit.
---------------------------------------------------------------------------
La section `env` (ci-dessous) est exécutée avant le code utilisateur.
Son contenu n'est pas visible de l'utilisateur mais tout ce qui y est défini
est ensuite disponible dans l'environnement.
Si le code de la section ENV lève une erreur, rien d'autre ne sera exécuté.
"""
# --- PYODIDE:env --- #
class Stack:
""" (Interface à décrire dans l'énoncé) """
def __init__(self): self.__stk=[]
def push(self, v): self.__stk.append(v)
def pop(self): return self.__stk.pop()
def is_empty(self): return not self.__stk
# --- PYODIDE:ignore --- #
"""
La section `code` est l'Ă©tat initial du code fourni Ă l'utilisateur dans
l'Ă©diteur, Ă l'exclusion des tests publics (voir section `tests`).
"""
# --- PYODIDE:code --- #
def est_pair(n):
...
# --- PYODIDE:ignore --- #
"""
La section `corr` contient le code qui sera affiché dans la correction, sous l'IDE.
"""
# --- PYODIDE:corr --- #
def est_pair(n):
return not n%2
# --- PYODIDE:ignore --- #
"""
La section `tests` contient les tests publics qui seront affichés sous le code
utilisateur, dans l'Ă©diteur.
"""
# --- PYODIDE:tests --- #
assert est_pair(3) is False
assert est_pair(24) is True
# --- PYODIDE:ignore --- #
"""
La section `secrets` contient les tests secrets pour les validations. Ces tests ne sont
pas visibles par l'utilisateur.
ATTENTION :
Il est impératif d'utiliser des messages dans les assertions des tests secrets,
sinon l'utilisateur ne peut pas déboguer son code car `print` est désactivé
durant ces tests ! (sauf si... => Voir les options de configuration)
Ă€ vous de choisir le niveau d'information que vous voulez fournir dans le message.
Par ailleurs, il est conseillé d'utiliser une fonction pour éviter que des variables
des tests ne se retrouvent dans l'environnement global.
"""
# --- PYODIDE:secrets --- #
def tests():
for n in range(100):
val = est_pair(n)
exp = n%2 == 0
msg = f"est_pair({n})" # Minimum vital
msg = f"est_pair({n}): valeur renvoyée {val}" # Conseillé
msg = f"est_pair({n}): {val} devrait ĂŞtre {exp}" # La totale
assert val == exp, msg
tests() # Ne pas oublier d'appeler la fonction de tests... ! x)
del tests # Si vous ne voulez pas laisser de traces...
# --- PYODIDE:post --- #
# La section post contient du code de "nettoyage", à appliquer systématiquement
# après que le code et les tests aient été lancés.
# Ce contenu est exécuté même si une erreur a été levée précédemment, SAUF si
# cette erreur provient de la section ENV.
Validité#
Toutes les sections sont optionnelles, mais pour être considéré valide, un fichier python doit respecter les règles suivantes :
- Les noms des sections doivent être ceux décrits dans le tableau en haut de cette page. Tout autre nom lèvera une erreur.
- Chaque section ne peut être déclarée qu'une fois (sauf la section
ignore, qui peut être réutilisée autant de fois que nécessaire). - Quand une section est définie, elle ne peut pas être vide. Si vous ne souhaitez pas utiliser une section, supprimez son contenu ainsi que le commentaire annonçant cette section, ou bien ajoutez un commentaire dans la section en question.
- L'ordre des sections dans le fichier n'a techniquement aucune importance pour les exécution dans Pyodide.
-
Selon la configuration de la section
idesdu pluginpyodide_macros, des contraintes peuvent être imposées ou non sur l'existence de certaines sections ou fichiers par rapport à d'autres.Si toutes les options sont laissées par défaut, une erreur est levée dans les cas suivants :
Présence secretsPrésence corrou REMarquesIDE(..., MAX=...)Option de configuration correspondant / ides.forbid_secrets_without_corr_or_REMs/ ides.forbid_hidden_corr_and_REMs_without_secrets\(\infty\) ides.forbid_corr_and_REMs_with_infinite_attempts
Les fichiers REM.md et VIS_REM.md #
Ces fichiers sont spécifiques aux IDEs.
mermaid. Il est par contre possible d'y utiliser des syntaxes Latex.
Lorsque l'utilisateur passe tous les tests ou consomme tous les essais disponibles, le contenu du fichier REM est affiché dans une admonition repliée (contenant également le code de la correction quand elle existe).
Le contenu de VIS_REM est quant à lui affiché au mêmes moments mais en-dessous de l'admonition repliée, de manière à ce que son contenu soit tout de suite visible par l'utilisateur.
L'admonition de la partie "VIS_REM" dans l'image ci-contre n'est pas ajoutée automatiquement : elle est définie dans le fichier VIS_REM lui-même.
... Et c'est tout !
# Tests(insensible Ă la casse)(Ctrl+I)
(Alt+: ; Ctrl pour inverser les colonnes)
(Esc)