Pyodide-Mkdocs-Theme : Ăditeurs & terminaux python dans MkDocs#
Version actuelle : 4.2.6
l'environnement pyodide est en cours de démarrage.
Mise Ă jour depuis pyodide-mkdocs
Si vous voulez mettre à jour un projet créé avec pyodide-mkdocs vers pyodide-mkdocs-theme, consultez la rubrique MAJ depuis pyodide-mkdocs.
Introduction#
Pyodide-MkDocs-Theme est un thÚme pour MkDocs qui permet de construire des sites pouvant intégrer, cÎté client:
- des IDEs (Ă©diteurs de code),
- des consoles python interactives,
- un juge en ligne pour tester des fonctions rédigée par l'utilisateur, associé à des corrections et remarques,
- et quelques autres fonctionnalités variées (qcms, ...).
Garanties :
- Sans cookie
- Sans inscription
- Créé par des enseignants pour les enseignants
"CĂŽtĂ© cuisine", le thĂšme est fourni avec un ensemble de fonctionnalitĂ©s prĂȘtes Ă l'emploi pour faciliter la vie du rĂ©dacteur :
- Le thĂšme Ă©tend
mkdocs-material, donc toutes les fonctionnalités de ce dernier sont disponibles. - Préconfiguration de MathJax, pour utiliser des expressions LaTex.
- Installation "one shot" : installer le thÚme installe également toutes les dépendances.
Ce projet est une refonte du prototype pyodide-mkdocs créé par Vincent Bouillot.
Comment ça marche?
La technologie permettant ce tour de force s'appelle Pyodide. Elle est associée à des éléments javascript, comme jquery.terminal et ACE Editor.
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 depuis Javascript.
Aperçus#
Créer des IDEs#
Une installation du thÚme permet d'obtenir l'éditeurs ci-dessous, en ajoutant cette commande dans un fichier markdown et les fichiers nécessaires à la création de l'IDE :
{{ IDE('exo') }}
Le thĂšme propose un Ă©cosystĂšme complet avec :
- Gestion de bibliothĂšques de codes python.
- Solutions pour téléverser/télécharger des fichiers.
- Gestion des options via des fichiers de métadonnées.
- ...
Outre toutes les fonctionnalités proposées, le thÚme reste particuliÚrement flexible !
En effet, il est toujours possible de :
- DĂ©finir vos propres macros, Ă utiliser en plus de celles du thĂšme.
- Personnaliser les styles et les Ă©lĂ©ments javascript, de mĂȘme que les plugins, extensions, ... Comme avec n'importe quelle documentation MkDocs !
Créer des qcms#
Un QCM avec mélange automatique des questions (bouton en bas pour recommencer)
(Une description additionnelle peut ĂȘtre ajoutĂ©e au dĂ©but de l'admonition...)
-
On a saisi le code suivant :
n = 8 while n > 1: n = n // 2Que vaut
naprÚs l'exécution du code ?- 0
- 1
- 2
- 4
-
Quelle est la machine qui va exécuter un programme JavaScript inclus dans une page HTML ?
- La machine de lâutilisateur sur laquelle sâexĂ©cute le navigateur web.
- La machine de lâutilisateur ou du serveur, selon celle qui est la plus disponible.
- La machine de lâutilisateur ou du serveur, suivant la conïŹdentialitĂ© des donnĂ©es manipulĂ©es.
- Le serveur web sur lequel est stockée la page HTML.
-
Cocher toutes les bonnes réponses, avec :
meubles = ['Table', 'Commode', 'Armoire', 'Placard', 'Buffet']-
meubles[1]vautTable -
meubles[1]vautCommode -
meubles[4]vautBuffet -
meubles[5]vautBuffet
-
Installation#
Mise Ă jour depuis pyodide-mkdocs
Presque toutes les fonctionnalitĂ©s de pyodide-mkdocs restent prĂ©sentes dans pmt-pypi, mais certaines modifications ont dĂ» ĂȘtre apportĂ©es au projet.
Ainsi, le passage Ă la version "thĂšme" nĂ©cessitera d'appliquer quelques modifications Ă votre documentation, aussi bien du cĂŽtĂ© de l'environnement (packages installĂ©s) que de la documentation elle-mĂȘme.
Voir la page concernant la mise Ă jour vers pyodide-mkdocs-theme, si c'est ce que vous voulez faire.
Installation via pip #
Le thĂšme fonctionne avec Python 3.8+ et est disponible sur PyPI. Il peut donc ĂȘtre installĂ© dans n'importe quel projet en exĂ©cutant cette commande dans un terminal, sur une machine avec une connexion internet :
pip install pyodide-mkdocs-theme
DĂ©marrer un nouveau projet#
Si le travail est effectué en local et une fois le thÚme installé, il est possible de démarrer un nouveau projet de documentation grùce à l'un des scripts disponibles avec le thÚme :
python -m pyodide_mkdocs_theme --new PROJECT_NAME
Cette commande, exécutée dans un terminal, crée un nouveau dossier nommé PROJECT_NAME dans le répertoire en cours, et y ajoute les fichiers de base pour démarrer un projet avec le thÚme :
Fichiers & dossiers créés
...
âââ PROJECT_NAME
âââ docs
â âââ index.md
â âââ exo.py
âââ .gitignore
âââ main.py
âââ mkdocs.yml
âââ requirements.txt
mkdocs.yml, avec une configuration minimale nĂ©cessaire pour le thĂšme. Ne pas oublier d'y modifier ensuite les champssite_nameetsite_url.requirements.txt, qui contient toutes les dĂ©pendances du projet..gitignore, avec des rĂ©glages gĂ©nĂ©riques pour un projet de documentation avec python.main.py, avec la logistique pour modifier certains messages du thĂšme en place. Ce fichier est optionnel et peut ĂȘtre supprimĂ© ou modifiĂ© (ajout de macros personnalisĂ©es).docs/index.mdetdocs/exo.py, qui donnent des exemples d'utilisation des macros du thĂšme.
DĂ©pendances #
Le thĂšme est compatible python 3.8+.
Les dépendances sont téléchargées et installées automatiquement lors de l'installation :
Comme le thÚme hérite de mkdocs-material toutes les fonctionnalités de ce dernier sont également disponibles.
Pour les versions de pyodide-mkdocs-theme antérieures à la v2.2.0
Gestion des plugins de mkdocs-material
Pour les versions strictement antĂ©rieures Ă la 2.2.0, les plugins issus de mkdocs-material devaient ĂȘtre prĂ©fixĂ©s en leur ajoutant material/ lors de leur enregistrement dans mkdocs.yml:plugins :
material/blog
material/group
material/info
material/offline
material/privacy
material/search
material/social
material/tags
Ă partir de la version 2.2.0, c'est l'inverse : ces plugins doivent maintenant ĂȘtre enregistrĂ©s sans prĂ©fixes ou ils ne fonctionneront plus correctement.
Si la notion de dossier partials vous parle, vous pourriez ĂȘtre Ă©galement concernĂ©s par ceci :
Ă partir de la mĂȘme version, PMT utilise 2 nouvelles surcharges de fichiers de material, dans custom_dir/partials: content.html et header.html.
Voici pour rappel la liste complÚte des fichiers surchargés :
content.htmlcopyright.htmlfooter.htmlheader.htmlsocial.html
Si vous avez surchargé l'un de ces fichiers, il vous faudra aller récupérer les versions utilisées dans PMT pour y inclure vos modifications.
mkdocs.yml : réglages #
Danger
Si l'argument --file ou -F pointe vers un fichier existant, ce fichier sera écrasé sans demande de confirmation préalable.
Configuration par défaut pour le thÚme#
Si le thÚme est déjà installé, il est possible de récupérer un fichier mkdocs.yml préconfiguré en exécutant le script ci-dessous.
Il est Ă©galement possible de simplement afficher le contenu du fichier modĂšle dans le terminal, si l'argument --file est omis :
python -m pyodide_mkdocs_theme --yml --file "mkdocs_.yml"
Configuration du fichier#
Voici ci-dessous le contenu d'une configuration minimale requise pour utiliser le thĂšme avec mkdocs.
Ne pas utiliser navigation.instant
Le thĂšme n'est pas compatible avec l'outil navigation.instant de mkdocs-material.
Si cette extension est activée par mégarde, une erreur sera levée.
theme:
name: pyodide-mkdocs-theme
## features:
## - navigation.instant # /!\ Cette option est incompatible avec le thĂšme !
plugins:
- search
- pyodide_macros
on_error_fail: true # Fortement conseillé...
## exclude_docs nécessite mkdocs 1.6+ pour fonctionner correctement. Sinon, vous pouvez utiliser
## le plugin mkdocs-exclude Ă la place.
## Ne surtout pas mettre de commentaires sur la ligne d'exclusion des fichiers python... !
exclude_docs: |
**/*_REM.md
**/*.py
markdown_extensions:
- md_in_html # !!REQUIS!!
- admonition # !!REQUIS!! Blocs colorés: !!! info "ma remarque"
- attr_list # !!REQUIS!! Un peu de CSS et des attributs HTML, ex: { #id .class style="display:none" }
- pymdownx.details # !!REQUIS!! Admonition: ??? -> peuvent se déplier ; ???+ -> peuvent se replier.
- pymdownx.emoji: # !!REQUIS!! Ămojis: :boom:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.highlight # !!REQUIS!! Coloration syntaxique du code
- pymdownx.inlinehilite # !!REQUIS!! Coloration syntaxique pour les "code spans": `#!python code_python`
- pymdownx.snippets: # !!REQUIS!! Inclusion de fichiers
check_paths: true # Fortement conseillé...
- pymdownx.superfences: # !!REQUIS!!
custom_fences: # (custom_fences: uniquement si vous comptez utiliser mermaid)
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.arithmatex: # !!REQUIS!! Pour LaTex
generic: true
Changer la palette de couleurs#
Il est possible de modifier la palette de couleurs utilisée pour les modes "jour" et "nuit".
Comme le thÚme vient avec un réglage par défaut pour les modes jour/nuit, il est nécessaire de redéfinir l'intégralité de la palette de couleurs dans la section theme, pour que tout fonctionne correctement :
theme:
palette: # Palettes de couleurs jour/nuit
- media: "(prefers-color-scheme: light)"
scheme: default
primary: orange
accent: deep orange
toggle:
icon: material/weather-sunny
name: Passer au mode nuit
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: orange
accent: deep orange
toggle:
icon: material/weather-night
name: Passer au mode jour
Configuration du plugin du thĂšme, pyodide_macros#
Le thÚme vient avec son propre plugin, qui permet de mettre en place toutes les fonctionnalités nécessaires.
De trĂšs nombreuses options peuvent y ĂȘtre configurĂ©es pour modifier le comportement du thĂšme selon vos besoins.
Hiérarchie complÚte de toutes les options du plugin
Les explications dĂ©taillĂ©es peuvent ĂȘtre trouvĂ©es dans cette page.
plugins:
- pyodide_macros:
args:
IDE:
SANS: ""
WHITE: ""
REC_LIMIT: -1
MERMAID: false
AUTO_RUN: false
MAX: 5
LOGS: true
MODE: null
MIN_SIZE: 3
MAX_SIZE: 30
TERM_H: 10
TEST: ""
TWO_COLS: false
STD_KEY: ""
EXPORT: false
terminal:
SANS: ""
WHITE: ""
REC_LIMIT: -1
MERMAID: false
AUTO_RUN: false
TERM_H: 10
FILL: ""
py_btn:
SANS: ""
WHITE: ""
REC_LIMIT: -1
ICON: ""
HEIGHT: null
WIDTH: null
SIZE: null
TIP: "Exécuter le code"
TIP_SHIFT: 50
TIP_WIDTH: 0.0
WRAPPER: "div"
MERMAID: false
AUTO_RUN: false
run:
SANS: ""
WHITE: ""
REC_LIMIT: -1
MERMAID: false
multi_qcm:
description: ""
hide: false
multi: false
shuffle: false
shuffle_questions: false
shuffle_items: false
admo_kind: "!!!"
admo_class: "tip"
qcm_title: "Question"
tag_list_of_qs: null
DEBUG: false
figure:
div_id: "figure1"
div_class: ""
inner_text: "Votre tracé sera ici"
admo_kind: "!!!"
admo_class: "tip"
admo_title: "Votre figure"
p5_buttons: null
build:
deprecation_level: "error"
encrypted_js_data: true
forbid_macros_override: true
ignore_macros_plugin_diffs: false
limit_pypi_install_to: null
load_yaml_encoding: "utf-8"
macros_with_indents: []
meta_yaml_allow_extras: false
meta_yaml_encoding: "utf-8"
python_libs: ["py_libs"]
skip_py_md_paths_names_validation: false
tab_to_spaces: -1
ides:
ace_style_dark: "tomorrow_night_bright"
ace_style_light: "crimson_editor"
deactivate_stdout_for_secrets: true
decrease_attempts_on_user_code_failure: "editor"
editor_font_family: "monospace"
editor_font_size: 15
encrypt_alpha_mode: "direct"
encrypt_corrections_and_rems: true
export_zip_prefix: ""
export_zip_with_names: false
forbid_corr_and_REMs_with_infinite_attempts: true
forbid_hidden_corr_and_REMs_without_secrets: true
forbid_secrets_without_corr_or_REMs: true
show_only_assertion_errors_for_secrets: false
qcms:
forbid_no_correct_answers_with_multi: true
terms:
cut_feedback: true
stdout_cut_off: 200
testing:
empty_section_fallback: "skip"
include: "null"
load_buttons: null
page: "test_ides"
force_render_paths: ""
include_dir: ""
include_yaml: []
j2_block_end_string: ""
j2_block_start_string: ""
j2_comment_end_string: ""
j2_comment_start_string: ""
j2_variable_end_string: ""
j2_variable_start_string: ""
module_name: "main"
modules: []
on_error_fail: false
on_undefined: "keep"
render_by_default: true
verbose: false
Plugins : piĂšges Ă Ă©viter#
Tous les plugins ne s'ignorent pas les uns les autres, et il peut parfois y avoir des interactions indésirables lors de leur enregistrement, voire des plantages durant un build/serve s'ils sont enregistrés dans un ordre inapproprié. Le problÚme principal étant que c'est en général à l'utilisateur de découvrir quel est le bon ordre...
Voici quelques informations glanées ici et là concernant les enregistrements des plugins.
| Plugin | Contrainte d'enregistrement |
|---|---|
awesome-pages |
Toujours en premier (en fait, avant tags) |
search |
Toujours en premier (ou juste aprĂšs awesome-pages / plugin de material) |
tags |
Toujours aprĂšs awesome-pages / plugin de material |
sqlite-console |
Toujours aprĂšs search et pyodide_macros |
exclude-search |
Toujours aprĂšs search |
glightbox |
Pas de contrainte au niveau de l'ordre de déclaration pour le plugin mkdocs-glightbox mais, s'il est utilisé, il faut ajouter la classe html skip_light_box dans l'option skip_classes afin que les boutons du thÚme soient affichés correctement. |
Pour les versions de pyodide-mkdocs-theme antérieures à la v2.2.0
Gestion des plugins de mkdocs-material
Pour les versions strictement antĂ©rieures Ă la 2.2.0, les plugins issus de mkdocs-material devaient ĂȘtre prĂ©fixĂ©s en leur ajoutant material/ lors de leur enregistrement dans mkdocs.yml:plugins :
material/blog
material/group
material/info
material/offline
material/privacy
material/search
material/social
material/tags
Ă partir de la version 2.2.0, c'est l'inverse : ces plugins doivent maintenant ĂȘtre enregistrĂ©s sans prĂ©fixes ou ils ne fonctionneront plus correctement.
Si la notion de dossier partials vous parle, vous pourriez ĂȘtre Ă©galement concernĂ©s par ceci :
Ă partir de la mĂȘme version, PMT utilise 2 nouvelles surcharges de fichiers de material, dans custom_dir/partials: content.html et header.html.
Voici pour rappel la liste complÚte des fichiers surchargés :
content.htmlcopyright.htmlfooter.htmlheader.htmlsocial.html
Si vous avez surchargé l'un de ces fichiers, il vous faudra aller récupérer les versions utilisées dans PMT pour y inclure vos modifications.
L'option use_directory_urls#
Le thÚme fonctionne quel que soit le réglage utilisé pour l'option use_directory_urls (par défaut: true).
Le choix des noms de fichiers markdown de la documentation n'a pas non plus d'effet sur la façon de renseigner les fichiers python utilisés pour les macros du thÚme (IDE, IDEv, terminal, ...), quels que soient :
- La valeur de l'option
use_directory_urls. - Le nom du fichier markdown source:
index.mdoumon_fichier.md(le second cas ayant un comportement à part pour certaines opérations, lorsqueuse_directory_urlsvauttrue).
Construire une version locale de la documentation
Moyennant certaines contraintes Ă respecter, il est possible de crĂ©er une version locale de la documentation, qui peut ĂȘtre ouverte directement dans un navigateur, aprĂšs avoir fait un mkdocs build.
Les réglages à modifier dans le fichier mkdocs.yml avant le build sont :
site_url: ""use_directory_urls: false- DĂ©sactiver le plugin de recherche (en commentant la ligne / Nota: le plugin n'empĂȘche pas le rendu, mais ne fonctionne pas normalement, dans cette situation).
Noter cependant qu'une connexion internet active reste indispensable au bon fonctionnement des pages : seul l'hébergement en ligne de la documentation est évité.
# Tests(insensible Ă la casse)(Ctrl+I)
(Alt+: ; Ctrl pour inverser les colonnes)
(Esc)