Aller au contenu

Pyodide-MkDocs 0.9.1 : Terminal et IDE dans MkDocs⚓︎

Introduction⚓︎

Pyodide-MkDocs est une solution technique permettant de créer un cours interactif à partir d'un site statique généré par MkDocs.

Il permet d'intégrer, dans le navigateur, côté client :

  • une console Python ;
  • un éditeur de code ;
  • un juge en ligne associé à des corrigés.

Garantie :

  • sans cookie
  • sans inscription
  • créé par un enseignant pour les enseignants
Solution

La technologie permettant ce tour de force s'appelle Pyodide.

Pyodide utilise WebAssembly pour faire le lien entre Python et Javascript et proposer un environnement permettant de manipuler le DOM Javascript avec Python, ou inversement de manipuler Python avec Javascript.

Aperçu⚓︎

Une installation complète permet d'obtenir ce résultat :

###
# Testsbksl-nlassert dentiste("j'ai mal") == "aia"bksl-nlassert dentiste("il fait chaud") == "iaiau"bksl-nlassert dentiste("") == ""bksl-nlbksl-nl 3/3

voyelles = ["a", "e", "i", "o", "u", "y"]bksl-nlbksl-nlbksl-nldef dentiste(texte):bksl-nl return "".join(c for c in texte if c in "aeiouy")bksl-nlbksl-nlbksl-nl# Testsbksl-nlassert dentiste("j'ai mal") == "aia"bksl-nlassert dentiste("il fait chaud") == "iaiau"bksl-nlassert dentiste("") == ""bksl-nlbksl-nlvoyelles = ['a', 'e', 'i', 'o', 'u', 'y']bksl-nlbksl-nldef dentiste(texte):bksl-nl resultat = ''bksl-nl for lettre in texte:bksl-nl if lettre in voyelles:bksl-nl resultat = resultat + lettrebksl-nl return resultatbksl-nlbksl-nl

A

Je n'ai qu'une remarque à faire : quel bel exercice !

Z

Installation⚓︎

Prérequis⚓︎

Ajout nécessaire⚓︎

À la racine du projet MkDocs (dans le dossier docs/), vous devez décompresser l'archive .zip téléchargeable en cliquant ici :

Plus d'information

Cela rajoutera les éléments suivants à votre configuration :

  • un dossier my_theme_customizations/ ;
  • un template HTML my_theme_customizations/main.html ;
  • un fichier CSS my_theme_customizations/pyodide-mkdocs/pyoditeur.css ;
  • trois fichiers Javascript my_theme_customizations/pyodide-mkdocs/interpreter.js, my_theme_customizations/pyodide-mkdocs/ide.js et my_theme_customizations/pyodide-mkdocs/utils.js;
  • six images de boutons.

Modification apportée⚓︎

Vous devez également modifier deux fichiers créés lors de votre installation de Material for Mkdocs.

Fichiers à modifier

Ajoutez la ligne appelée custom_dir dans la partie theme de votre fichier mkdocs.yml :

theme:
  name: material
  custom_dir: my_theme_customizations/

À votre fichier main.py, ajoutez les lignes comprises entre Debut copie et Fin copie du fichier main.py.

Il y a deux blocs : le bloc des python import et le bloc de code.

Syntaxe et exemples⚓︎

La syntaxe

{{ terminal() }}
Création d'un terminal vide. L'auto-complétion avec Tab et le rappel de l'historique (avec Ctrl＋R ) sont possibles.

{{ IDE() }}
Création d'un IDE vide, visuellement proche de Thonny. La zone de saisie se redimensionne automatiquement et autorise l'auto-complétion de type snippet avec Alt＋Space.

###

{{ IDEv() }}
Cette commande crée un IDE vide, avec division verticale.

###

{{ IDE('foo/bar/nom_de_fichier', MAX = 8, SANS = 'max,min') }}

  • Le fichier nom_de_fichier.py est chargée dans un IDE. Ce fichier doit être situé impérativement dans docs/scripts/foo/bar/.

  • MAX = 8 : indique le nombre maximal de tentatives de validation que l'élève peut effectuer. MAX = 1000 ou MAX = "+" permet de mettre ce nombre à l'infini. Valeur par défaut : MAX = 5 .

  • SANS = 'max,min' permet d'interdire l'utilisation des fonctions built-ins max et min.

Les IDE sont enregistrés à intervalle de temps régulier. Ils permettent également l'autocomplétion avec la combinaison de touches Alt＋Space.

###
benchmark = ['longueur([])==0', 'longueur([1,3,5,5])==4', 'longueur([0]py-str100)==100']bksl-nl ∞/∞
L = [5,3,4,1]bksl-nlbksl-nldef longueur(L: list) -> int:bksl-nl return bksl-nldef longueur(L: list) -> int:bksl-nl return len(L)bksl-nl

A

Remarque

Ceci est un exemple complexe de remarque.

La première ligne du fichier de remarque doit être vide

La syntaxe markdown est complètement préservée. Par exemple, un tableau :

a b c
1 2 3

Une admonition ?

Vous pouvez inclure des admonitions et des superfences dans vos remarques.

Z

{{ IDEv('foo/bar/nom_de_fichier', MAX = 1000) }}
Cette commande charge le fichier nom_de_fichier dans un IDE avec division verticale. Le fichier doit être dans docs/scripts/foo/bar/.

###
assert longueurpy-undajout([], []) == 0, 'longueurpy-undajout([], []) == 0'bksl-nlassert longueurpy-undajout([1, 3, 5, 5],[]) == 4, 'longueurpy-undajout([1, 3, 5, 5],[]) == 4'bksl-nlassert longueurpy-undajout([0]py-str100, [1]py-str20) == 120, 'longueurpy-undajout([0]py-str100, [1]py-str20) == 120'bksl-nl 3/3
T1 = [5,3,4,1]bksl-nlT2 = [1,2]bksl-nlbksl-nldef longueurpy-undajout(T1: list, T2: list) -> int:bksl-nl return bksl-nldef longueurpy-undajout(T1: list, T2: list) -> int:bksl-nl return len(T1) + len(T2)bksl-nl

A

Des admonitions en remarque

Yes, we can.

Oh yes, we can.

Toujours plus

Yes, we can.

Oh yes, we can.

Encore

Yes, we can.

Oh yes, we can.

Z

Détails techniques

Tous les IDE et les terminaux partagent le même namespace. On peut donc accéder à n'importe quelle fonction créée dans n'importe quel IDE ou terminal.

C'est un comportement qui a l'avantage de pouvoir proposer des exercices où l'on construit petit à petit un code complexe mais qui fera l'objet de changement important à l'avenir.