Mise à jour vers pyodide-mkdocs-theme

Passage de mkdocs-pyodide à pyodide-mkdocs-theme

Beaucoup de sites avec Python interactif ont été développés en utilisant mkdocs-pyodide créé par Vincent Bouillot.
Le passage à pyodide-mkdocs-theme écrit par Frédéric Zinelli, permet beaucoup d'évolutions présentées ci-dessous, et corrige des bugs.

Nouveau après la mise à jour :
Tant que ce sablier (animé) est présent dans le bandeau supérieur, des éléments de la page sont inactifs :
l'environnement pyodide est en cours de démarrage.

I. Pourquoi faire une MAJ ?⚓︎

Une Mise à jour importante

Pyodide-MkDocs-Theme est un thème pour MkDocs, créé par Frédéric Zinelli.

Correction des bugs de la version précédantes de pyodide, fonctionalités rajoutées.
Exercices beaucoup plus faciles à écrire, avec seul fichier python (entre 1 et 4 dans la version précédante)
Exécution du code beaucoup plus rapide, ce qui est sensible pour les fonctions récursives et les boucles importantes.
facilité d'installation et de maintenance

Ce thème permet de construire des sites pouvant intégrer, côté client:

des IDE (éditeur 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, ...).

😊 Une fois la mise à jour effectuée, le site fonctionnera encore avec l'ancienne structure (plusieurs fichiers python pour un IDE par exemple). Il n'y a donc aucune inquiétude à avoir pour réaliser cette mise à jour.

Attention pour les qcm, les macros personelles, et l'option de taille d'IDE

Si des syntaxes (expliqué dans le III):

Markdown

{{ qcm( ... ) }}

ont été utilisées dans le site, il faudra les supprimer, et faire les modifications pour utiliser :

Markdown

{{ multi_qcm( ... ) }}

👉 Il est recommandé de faire une recherche des qcm sur votre site, avant MAJ, grâce à la barre de recherche située en haut à droite. Il faudra noter les pages qui contiennent des qcm, pour faire les modifications éventuelles.

Si vous avez réalisé des macros personnelles, il faudra être attentif à ne pas les perdre (expliqué dans le III).
Si vous avez utilisé :

Markdown

{{ IDE( 'exo', SIZE=45 ) }}

Il faudra le remplacer par

Markdown

{{ IDE( 'exo', MAX_SIZE=45 ) }}

Sinon cela mettra le pipeline en échec.

Remarque

Si vous n'avez jamais construit de site avec Python (pyodide) cette mise à jour ne vous est pas destinée. Le tutoriel présenté ici, est très simplifié, car il est destiné à la mise à jour de sites créés en utilisant le modèle proposé dans ce tutoriel ancien : Ancien tutoriel pour créer son site

Ce tutoriel s'adresse à des débutants avec GitLab.

👉 Pour des points particuliers, se référer au lien Documentation officielle pour la MAJ depuis les sites créés avec pyodide-mkdocs

Warning

L'essentiel des fonctionnalités de pyodide-mkdocs restent présentes dans pyodide-mkdocs-theme.

Documentation officielle de Pyodide Mkdocs Theme

Cependant, certaines modifications ont dû être apportées au projet, qui font que le passage à la version "thème" nécessitera quelques changements, aussi bien du côté de l'environnement (packages installés) que de la configuration et du contenu.

II. Créer une copie de sauvegarde de votre projet⚓︎

Indispensable avant de commencer

Faire un fork de votre projet, et le renommer (par exemple mon projet old). Vous allez modifier par la suite votre projet d'origine.

faire un fork

Warning

Le rendu du site ne sera possible qu'après avoir terminé toutes les modifications à réaliser.

III. Supprimer ou modifier des fichiers.⚓︎

Une fois cette copie de sauvegarde effectuée, revenir sur le projet à mettre à jour.

Supprimez le dossier my_theme_customizations

Supprimez le dossier my_theme_customizations et tout ce qu'il contient avec un clic droit sur le dossier.

Modifier ou supprimer le fichier main.py

Très important si vous avez utilisé des macros personnelles

Ne pas faire ce qui est proposé dans l'encadré qui suit, mais se reporter ici :

Si vous n'avez pas utilisé des macros personnelles

Supprimer le fichier main.py

Suppressions dans le dossier docs

Dans le dossier docs :

supprimer le dossier javascripts et tout ce qu'il contient
Dans le dossier xtrasupprimer le dossier javascripts et tout ce qu'il contient.
Dans le dossier xtra dans le dossier stylesheets supprimer le fichier qcm.css

Modifications du fichier mkdocs.yml

Dans le fichier mkdocs.yml

Vérifier la présence des lignes suivantes (les modifier si nécessaire)

YAML

site_url: !ENV [CI_PAGES_URL, "http://127.0.0.1:8000/"]
site_author: !ENV [CI_COMMIT_AUTHOR, "Nom d'auteur"]
repo_url: !ENV [CI_PROJECT_URL]
edit_uri: !ENV [EDIT_VARIABLE]

Vers la ligne n° 22 : section theme, supprimer (mettre des # en début de ligne) comme ci-dessous.
Vers la ligne n° 27 remplacer name: material par name: pyodide-mkdocs-theme
Vers la ligne n° 47 ne pas oublier de supprimer navigation.instant, car le thème n’est pas compatible avec cette option.

theme:
    favicon: assets/favicon.ico
    icon:
    logo: material/stairs-up
    #custom_dir: my_theme_customizations/
    name: pyodide-mkdocs-theme
    #font: false                     # RGPD ; pas de fonte Google
    #language: fr                    # français
    #palette:                        # Palettes de couleurs jour/nuit
    #- media: "(prefers-color-scheme: light)"
        #scheme: default
        #primary: indigo
        #accent: indigo
        #toggle:
            #icon: material/weather-sunny
            #name: Passer au mode nuit
    #- media: "(prefers-color-scheme: dark)"
        #scheme: slate
        #primary: black
        #accent: green
        #toggle:
            #icon: material/weather-night
            #name: Passer au mode jour
    features:
        #- navigation.instant
        #- navigation.tabs   Pour avoir le menu vertical il fallait supprimer ça
        - navigation.top
        - toc.integrate
        - header.autohide
        - content.code.annotate   # Pour les annotations de code deroulantes avec +

Vers la ligne n°66 section markdown_extensions: ajouter md_in_html au début markdown_extensions:

Vers la ligne n°89 remplacer

    - pymdownx.emoji:               # Émojis  :boom:
        emoji_index:     !!python/name:materialx.emoji.twemoji
        emoji_generator: !!python/name:materialx.emoji.to_svg

par :

    - pymdownx.emoji: # Émojis  :boom:
        emoji_index: !!python/name:material.extensions.emoji.twemoji
        emoji_generator: !!python/name:material.extensions.emoji.to_svg

markdown_extensions:
    - md_in_html
    - meta
    - abbr
    - def_list                      # Les listes de définition.
    - attr_list                     # Un peu de CSS et des attributs HTML.
    - footnotes                     # Notes[^1] de bas de page.  [^1]: ma note.
    - admonition                    # Blocs colorés  !!! info "ma remarque"
    - pymdownx.details              #   qui peuvent se plier/déplier.
    - pymdownx.caret                # Passage ^^souligné^^ ou en ^exposant^.
    - pymdownx.mark                 # Passage ==surligné==.
    - pymdownx.tilde                # Passage ~~barré~~ ou en ~indice~.
    - pymdownx.highlight:           # Coloration syntaxique du code
    - pymdownx.inlinehilite         # pour  `#!python  <python en ligne>`
    - pymdownx.snippets             # Inclusion de fichiers externe.
    - pymdownx.tasklist:            # Cases à cocher  - [ ]  et - [x]
        custom_checkbox:    false   #   avec cases d'origine
        clickable_checkbox: true    #   et cliquables.
    - pymdownx.tabbed:              # Volets glissants.  === "Mon volet"
        alternate_style: true 
    - pymdownx.keys:                # Touches du clavier.  ++ctrl+d++
        separator: "\uff0b"
    - pymdownx.emoji: # Émojis  :boom:
        emoji_index: !!python/name:material.extensions.emoji.twemoji
        emoji_generator: !!python/name:material.extensions.emoji.to_svg
    - pymdownx.superfences:
        custom_fences:
        - name: mermaid
            class: mermaid
            format: !!python/name:pymdownx.superfences.fence_code_format
    - pymdownx.arithmatex:
        generic: true
    - toc:
        permalink: ⚓︎
        toc_depth: 2

Vers la ligne n°103 section plugins, vous devez avoir ceci, dans le même ordre :

A copier

plugins:

    - awesome-pages:
        collapse_single_pages: true

    - search
    - tags:
        tags_file: tags.md
    - pyodide_macros:
        # Vous pouvez ajouter ici tout réglage que vous auriez ajouté concernant les macros:
        on_error_fail: true     # Il est conseillé d'ajouter celui-ci si vous ne l'utilisez pas.
        build:
          python_libs:  # Pour avoir la tortue Python
            - turtle
          tab_to_spaces: 4  # Pour convertir les tabulations en 4 espaces


# En remplacement de mkdocs-exclude. Tous les fichiers correspondant aux patterns indiqués seront
# exclu du site final et donc également de l'indexation de la recherche.
# Nota: ne pas mettre de commentaires dans ces lignes !
exclude_docs: |
    **/*_REM.md
    **/*.py

Vers les lignes n°130 : supprimer (mettre des # en début de ligne) comme ci-dessous.

YAML

#extra_javascript:
#- xtra/javascripts/mathjax-config.js       Supprimé pour MAJ pyodide             
#- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

extra_css:
  #- xtra/stylesheets/qcm.css ##       Supprimé pour MAJ pyodide  
  - xtra/stylesheets/ajustements.css  # ajustements

Ajouter le répertoire turtle

Il faut mettre le dossier turtle à la racine du site à télécharger ici : Clic droit, puis "Enregistrer la cible du lien sous"
Décompresser le fichier turtle.zip puis mettre le dossier turtle à la racine du projet.

turtle

Vous obtiendrez :

turtle à la racine

Modifications du fichier requirements.txt

Remplacer le contenu du fichier requirements.txt par :

code à copier

pyodide-mkdocs-theme
mkdocs-awesome-pages-plugin
mkdocs-enumerate-headings-plugin
mkdocs-exclude-search

Le fichier tags.md

Dans le dossier docs se trouve en principe un fichier tags.md

Si ce n'est pas le cas, le rajouter :

code à copier pour le fichier tags.md

# 🏷️ Tags

Les QCM

Si des syntaxes (expliqué dans le III):

Markdown

{{ qcm( ... ) }}

ont été utilisées dans le site, il faudra les supprimer, et faire les modifications pour utiliser :

Markdown

{{ multi_qcm( ... ) }}

Exemple de code à supprimer

👉 Par exemple, il faut supprimer ceci :

Markdown

Question 1 : $2^3=$

{{ qcm(["9", "8", "Je ne sais pas", "6"], [2], shuffle = True) }}

Exemple de code de remplacement

On peut remplacer le code précédant par :

Version longue

code à copier

{{ multi_qcm(
    [
        "Compléter : $2^3=$",
        [
            "9",
            "8",
            "Je ne sais pas",
            "6",
        ],
        [2],
    ],

    multi = False,
    qcm_title = "Puissances",
    shuffle = True,
) }}

Version courte

On peut aussi tout simplement écrire de façon plus concise :

code à copier

{{ multi_qcm(
    ["Compléter : $2^3=$", ["9", "8", "Je ne sais pas", "6"],[2],],
    multi = False,
    qcm_title = "Puissances",
    shuffle = True,
) }}

Tout savoir sur les qcm

Se reporter ici : Documentation officielle sur les qcm

Les noms de dossiers et de fichiers

Attention, les seuls caractères autorisés pour les noms de fichiers sont : les lettres, chiffres, traits d’union ou traits bas, et rien d’autre.

Les caractères spéciaux, espaces et lettres accentuées sont interdits.

👉 Penser à modifier ces noms si nécessaire.

Les fichiers .pages

La syntaxe arrange va devenir obsolète. Dans les fichiers .pages remplacer arrange par nav.

Code exemple pour un fichier `.pages`

title: Mon titre
nav:
    - page1.md
    - page2.md
    - repertoire_1
    - page3.md
    - repertoire_2

IV. Terminer⚓︎

Faire le commit

Faire le commit, et vérifier le rendu du site.

V. En cas d'erreur⚓︎

En cas d'échec du pipeline

echec pipeline

😅 Ce n'est pas très grave, pas de panique !

cliquer echec

Vous obtenez quelquechose comme ceci :

en echec

Cliquer sur J"obs ayant échoué" puis lire le message qui s'affiche.

message echec

😏 Il n'y a plus qu'à comprendre le message d'erreur (c'est un peu effrayant, mais cela permet de résoudre le problème), et rectifier avant de faire un nouveau commit ...

Dans l'exemple ci-dessus on lit : Nav entry "fractales" not found. [.pages] . En effet, dans le dfichier .pages je fais référence à un dossier "fractales" qui avait été supprimé du site. Il suffit de supprimer la ligne correspondante du fichier .pages, de faire un commit, et le nouveau pipeline ne sera pas en échec.

Erreurs fréquentes qui mettent un pipeline en échec

Une macro qui n'existe pas (voir pour les qcm par exemple) met le pipeline en échec.
Utiliser une section vide dans un fichier python : Sections vides
Une erreur possible : utilisation de l'ancienne option SIZE pour la taille d'un IDE. Il faut le remplacer par MAX_SIZE (Voir le I.)
Un fichier .pages incorrect
Un nom de fichier est invalide : Le thème n’autorise plus les caractères accentués, caractères spéciaux, espaces …
Voir : Mettre à jour les fichiers

Crédits⚓︎

Merci à Frédéric Zinelli qui a créé ce thème, et une documentation très détaillée, dont je me suis très largement inspirée.

Documentation détaillée de pyodide-mkdocs-theme par F. Zinelli