Aller au contenu

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

Introduction⚓︎

Pyodide-MkDocs est une solution technique permettant de créer un cours interactif à partir d'un site 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 avec Python, ou de manipuler Python avec Javascript.

Aperçu⚓︎

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

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

Démarrage rapide⚓︎

Vous ne connaissez rien à MkDocs et vous souhaitez vous y mettre ? Des mots comme yaml, javascript, Pyodide ou templates Jinja vous font peur ?

Commencez en douceur en partant d'un repo MkDocs aux dernières normes en vigueur : clonez le répertoire Git !

Installation⚓︎

On part d'une installation comme indiqué sur ce lien avec le plugin macro, préalablement installé.

L'installation demande de rajouter à cette configuration les éléments suivants.

Modification apportée :

  • fichier YML mkdocs.yml ;
  • fichier de macro main.py ;

Ajout nécessaire :

  • un dossier my_theme_customizations/ à la racine du projet MkDocs ;
  • un template HTML my_theme_customizations/main.html ;
  • un fichier CSS my_theme_customizations/pyodide-mkdocs/pyoditeur.css ;
  • deux fichiers Javascript my_theme_customizations/pyodide-mkdocs/interpreter.js et my_theme_customizations/pyodide-mkdocs/ide.js ;
  • six images de boutons.

Fichier YML mkdocs.yml⚓︎

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

theme:
  name: material
  custom_dir: my_theme_customizations/

Fichier macro Python main.py⚓︎

À votre fichier main.py, ajoutez les lignes du fichier main.py. Vous devez disposer de Python 3.5 au minimum.

Création du dossier custom_dir⚓︎

N'oubliez pas de créer le dossier my_theme_customizations/ à la racine du projet MkDocs.

Dans ce dossier, ajoutez le template Jinja main.html.

Fichier CSS pyoditeur.css⚓︎

Afin de coller au thème du site, recopiez et ajoutez le fichier pyoditeur.css au dossier my_theme_customizations/pyodide-mkdocs/.

Couleurs

Si vous avez opté pour d'autres couleurs, c'est là que vous pourrez faire les modifications de l'éditeur.

Fichiers javascripts interpreter.js et ide.js⚓︎

Deux fichiers Javascript interpreter.js et ide.js sont nécessaires :

Ces fichiers doivent être placés dans le dossier : my_theme_customizations/pyodide-mkdocs/.

Images des boutons⚓︎

Les boutons doivent être placés à cette adresse : /docs/images/buttons/. Il existe six boutons que vous pouvez récupérer en téléchargeant l'archive.

Syntaxe et exemples⚓︎

Syntaxe Markdown⚓︎

La syntaxe

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

{{ IDE() }}
Création d'un IDE (~ Thonny) vide. La flèche permet de lancer le code tapé dans la zone de saisie (avec les numéros de ligne). La zone de saisie se redimensionne automatiquement et autorise l'auto-complétion de type snippet avec Tab.

###

{{ IDEv() }}
Cette commande crée un IDE vide, avec division verticale. La flèche permet de lancer le code tapé dans la zone de saisie (avec les numéros de ligne). La zone de saisie se redimensionne automatiquement et autorise l'auto-complétion de type snippet avec Tab.

###
"

{{ IDE('foo/bar/nom_de_fichier', MAX = 8, SANS = 'max,min') }}
Cette commande charge le fichier nom_de_fichier.py dans un IDE. Le fichier doit être dans docs/scripts/foo/bar/. Ne pas oublier les guillemets.

MAX = 8 indique le nombre maximal de tentatives de validation que l'élève peut effectuer. MAX = 1000 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 AltSpace.

###
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/.

###
"
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

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.

Exemples⚓︎

L'exemple ci-dessous, obtenu avec {{ IDEv('exo2') }}. N'hésitez pas à modifier le code pour calculer la moyenne, l'écart-type, afficher cela dans le terminal etc.

###
"
b1 = ['somme([]) == None', 'somme([1]) == 1', 'somme([1,2]) == 3', 'somme([-1,1]) == 0']bksl-nlb2 = ['sommation([1]) == 1', 'sommation([1,2]) == 3', 'sommation([-1,1]) == 0']bksl-nlbksl-nlbenchmark = (b1, b2)bksl-nl 5/5

def sommation(T: list) -> int:bksl-nl a = 0bksl-nl for nombre in T:bksl-nl a = a + nombrebksl-nl return abksl-nlbksl-nlbksl-nldef somme(L: list) -> None | int:bksl-nl return None if len(L) == 0 else sum(L)bksl-nlbksl-nldef somme(L: list[int]) -> int:bksl-nl return None if len(L) == 0 else sum(L)bksl-nl

A

Remarque sur la solution

C'est simple mais il faut être vigilant.

Une autre remarque est possible

Toujours simple mais toujours vigilant.

Z

L'exemple ci-dessous a été obtenu avec {{ IDE('algo_glouton') }}.

###

# dictionnaire :bksl-nl# - clé : nom de l'objetbksl-nl# - valeur : tableau [poids, prix]bksl-nlinventaire = {"A": [13,700], "B": [12,650], "C": [6,250], "D": [6,400],"E": [5, 100]}bksl-nlbksl-nl# Calcule la valeur massique en divisant la 2ème valeur du tableau par la premièrebksl-nl# on ajoute cela à la valeur du dictionnairebksl-nlfor objet, (poids, prix) in inventaire.items():bksl-nl inventaire[objet].append(prix/poids)bksl-nlbksl-nl# Trie le tableau en ordre décroissant suivant la valeur massique.bksl-nldef f(dico: dict, col = 2):bksl-nl tableaupy-undtrié = sorted(dico.items(), key = lambda a: a[1][col], reverse=True)bksl-nl return {clé:valeur for clé, valeur in tableaupy-undtrié}bksl-nlbksl-nlbksl-nlinventaire = f(inventaire, 2)bksl-nlbksl-nlpoidspy-undmax = 30bksl-nlbksl-nl# Algorithme gloutonbksl-nldef gloutonnerie(inventaire : dict, poidspy-undmax:int=30):bksl-nl sacpy-undapy-unddos = []bksl-nl poidspy-undsac = 0bksl-nl for objet, (poids, prix, vpy-undmassique) in inventaire.items():bksl-nl if poidspy-undsac + poids <= poidspy-undmax:bksl-nl sacpy-undapy-unddos.append(objet)bksl-nl poidspy-undsac += poidsbksl-nl return sacpy-undapy-unddos, poidspy-undsacbksl-nlbksl-nlprint(gloutonnerie(inventaire, poidspy-undmax))bksl-nlbksl-nlbksl-nl

A

Z