MAJ depuis pyodide-mkdocs

Attention

L'essentiel des fonctionnalités de pyodide-mkdocs restent présentes dans le thème.

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

Évolutions des macros#

Voici une vue d'ensemble des macros conservées, modifiées ou supprimées, en passant de pyodide-mkdocs à pyodide-mkdocs-theme :

Devenir	Macros
Conservées mais modifiées	`IDE` `IDEv` `multi_qcm` `py` `terminal`
Ajoutées	`run` `figure` `py_btn` `section` `IdeTester` (à NE PAS UTILISER : sert pour les tests des IDEs)
Supprimées	`qcm` `cours` `exercice` `ext` `html_fig` `numworks` `python_carnet` `python_ide` `tit` `mult_col`

À propos des macros modifiées

Les anciens arguments restent valides, mais la plupart de ces macros se sont vues ajoutées d'autres arguments.

En particulier, la méthode d'identification des IDEs sur le site a été modifiée, et les macros IDE et IDEv on maintenant un argument ID:Optional[int], qui permet au code du thème d'identifier sans ambiguïtés deux IDEs qui utiliseraient les mêmes fichiers python. C'est cet argument que vous risquez de devoir ajouter ici ou là dans la documentation existante, après être passés au thème.

Exemples:

* Page A: `IDE('py_sources/exo1', ID=1)`
* Page A: `IDE('py_sources/exo1', ID=2)` (ailleurs dans la même page)
* Page B: `IDE('py_sources/exo1', ID=3)`

En cas de problèmes, vous pouvez demander de l'aide sur le forum NSI-Inria ou ouvrir un ticket sur le dépôt.

Breaking changes#

Certaines fonctionnalités ne sont plus supportées ou ont évolué :

Depuis la version 3.0.0 : Il n'est plus possible de déclarer le nombre d'essais pour les IDEs directement dans le fichier python, en démarrant le fichier avec #MAX=N.
Les noms de dossiers et les noms des fichiers python et markdown dans la documentation ne peuvent plus contenir d'espaces, caractères accentués/spéciaux, ... Ceci permet de garantir le bon fonctionnement des différentes macros.
Si des caractères non autorisés sont rencontrés, une erreur est levée (voir la section 7 pour gérer ce type d'erreur).
Les noms de chemins ne peuvent contenir que les caractères suivants:
- des lettres ASCII (majuscules et minuscules)
- des chiffres
- des points, traits d'union ou traits bas.
Le mode benchmark de pyodide-mkdocs, pour les tests, n'est plus supporté.
L'argument SIZE des macros IDE est remplacé par l'argument SIZE_MAX, qui fixe la hauteur maximale d'un éditeur (en nombre de lignes).
Le mécanisme de création automatique des messages d'erreur pour les assertions dans les IDE a été remplacé par un mécanisme plus robuste, mais plus simple.
À propos des nouveaux messages d'erreur automatiques pour les assertions...

pyodide-mkdocs pratiquait une sorte d'introspection du code pour reconstruire un message en injectant automatiquement des informations/bouts de codes provenant de différents endroits. Il reconstruisait notamment les valeurs utilisées pour les arguments.

La logique employée posait de nombreux problèmes et le comportement n'était pas modulable, ce qui rendait les tests secrets "pas très secrets". Au final, il a été décidé de supprimer cette fonctionnalité et d'en faire une version plus robuste, mais aussi beaucoup plus simple.

Par défaut, le thème va reconstruire des messages mais ils seront probablement insuffisants pour donner un feedback digne de ce nom aux utilisateurs, si le code n'a pas été rédigé en prévision de cela.
Concrètement :
Feedback utileFeedback inexploitable
assert user_func(42) == [ [0,1,2], [1,2,3], [3,4,5], ]

Si cette assertion échoue, le code entier de l'assertion sera ajoutée au message :

... AssertionError: assert user_func(42) == [ [0,1,2], [1,2,3], [3,4,5], ] >>>
actual = user_func(42) expected = [ [0,1,2], [1,2,3], [3,4,5], ] assert actual == expected

Si cette assertion échoue, la même chose se produit, mais cette fois le message ne contient aucune information utile pour l'utilisateur !

... AssertionError: assert actual == expected >>>
Notez que ce changement de comportement par rapport à pyodide-mkdocs opère aussi sur les tests publics.

Voir également la configuration globale de l'argument LOGS des IDE.

Mise à jour#

Les informations données ci-dessous partent du principe que vous travaillez en local et téléversez vos modifications ensuite sur un dépôt via git.
Si vous construisez votre site en ne travaillant qu'en ligne, via la forge EN par exemple, il pourrait être plus simple de suivre le tuto dédié créé par Mireille Coilhac, en revenant ici pour d'éventuelles informations complémentaires.

1. Créer une copie de votre documentation/projet#

Selon votre aisance avec les outils de contrôle de versions ou d'environnement (git, venv, ...), modifiez soit la copie, soit la version d'origine.
Si vous n'êtes pas à l'aise avec tout cela, il est conseillé de garder la copie comme sauvegarde et de modifier le dossier d'origine. Gardez simplement en tête que vous aurez à finaliser la transition vers le thème avant de pouvoir refaire une mise à jour de votre site en ligne.

Quelques pièges à éviter

Conséquence directe : ne pas démarrer la transition vers le thème le dimanche soir si vous avez des choses à mettre à jour pour le lundi matin !
Si vous utilisez une nouvelle branche git, n'oubliez pas que les packages installés sont indépendants des branches de travail (si vous utilisez git de manière conventionnelle...). Donc travailler dans une nouvelle branche revient au même que de faire la mise à jour sans utiliser d'environnement virtuel, la branche de départ servant alors de sauvegarde du contenu projet, mais pas de l'environnement python.
Le travail avec un environnement virtuel n'est pas indispensable mais il facilite la transition, en permettant notamment de garder les deux versions du projet fonctionnelles. Si vous utilisez un environnement virtuel, il vous faudra par contre cloner votre projet, pour que les deux versions ne partagent pas le même environnement virtuel.

2. Supprimer les anciens fichiers#

Si vous avez apporté des modifications à certains éléments de pyodide-mkdocs (notamment le css ou des fonctions javascript) récupérez les fichiers concernés dans un dossier à part pour réintroduire ces changements ultérieurement.
Notez cependant que les modifications apportées au JS issu de pyodide-mkdocs ne pourront plus être incorporées facilement dans le thème. Si vous êtes dans cette situation, mieux vaut demander de l'aide sur le dépôt, ou sur le forum de l'INRIA si vous pouvez vous y inscrire.
Supprimez ensuite tout le contenu du custom_dir (qui devrait s'appeler my_theme_customizations si vous avez gardé l'organisation d'origine).
Conservez les personnalisations ajoutées dans votre custom_dir !

Si vous avez modifié le contenu du custom_dir, conservez ces modifications pour pouvoir les réintroduire plus tard.

Typiquement à conserver :
- Le contenu du sous-dossier partials (attention, pyodide-mkdocs-theme surcharge les fichiers suivants : content.html, copyright.html, footer.html, header.html et social.html. Si vous en aviez surchargés certains, il vous faudra récupérer ceux du thème et y incorporer vos modifications).
- Les modifications du fichier main.html peuvent être réintroduite dans certaines situations, mais il est fortement déconseillé de travailler via un override du fichier main.html avec le thème (raisons / solutions potentielles: les hooks de pyodide-mkdocs-theme).
- Des fonctions JS peuvent souvent être réintroduites via des fichiers docs/extras/javascripts/, moyennant une éventuelle réécriture et un enregistrement dans mkdocs.yml:extra_javascript.
- Les scripts chargés vias CDN peuvent en général être réintroduits dans mkdocs.yml:extra_javascript.
Voir la section sur la personnalisation via un custom_dir.
Supprimez le dossier zip/my_theme_customizations si vous l'aviez récupéré et/ou le fichier zip lui-même.
Supprimez le fichier main.py, si vous n'avez pas de macros personnalisées.
Sinon, vous pouvez garder le fichier/module là où il est, mais il vous faudra supprimer toutes les macros ayant les mêmes noms que celles définies par le thème (voir tableau en haut de cette page).
Dans votre dossier docs (ou ce que vous utilisez comme docs_dir), supprimez ces fichiers, si présents :
- javascripts/config.js
- javascripts/mermaid.js
- xtra/javascripts/mathjax-config.js
- xtra/stylesheets/qcm.css
- Nettoyer les sections extra_javascript et extras_css du fichier mkdocs.yml en supprimant les références aux fichiers ci-dessus quand elles existent.
  Si toutes les entrées sont supprimées, il faut également supprimer l'intitulé de section, extra_javascript ou extra_css

3. MAJ `requirements.txt`#

Il faut mettre à jour les dépendances de manière à ce que ce soit le thème qui impose les contraintes.

Si vous utilisez un fichier requirements.txt, l'idée est la suivante :

Ajouter pyodide-mkdocs-theme en tout premier.
Supprimer les dépendances ci-dessous si présentes dans votre fichier (le thème impose les contraintes sur ces packages) :
- mkdocs
- mkdocs-material
- mkdocs-macros-plugin

4. Installer le thème#

Rappels concernant le processus d'installation

Si vous êtes familiers des environnements virtuels, il est conseillé de faire la mise à jour dans un nouvel environnement.

Si ce n'est pas votre tasse de thé, gardez simplement en tête les points suivants :

Il faudra finir la mise à jour complète avant de retrouver un projet fonctionnel.
Sans environnement virtuel, les deux versions ne peuvent pas cohabiter en étant toutes les deux fonctionnelles, car les dépendances ne sont pas exactement les mêmes (version de material et du plugin des macros, notamment).
Il est toujours possible de passer d'une version à l'autre, mais il faut pour cela réinstaller toutes les dépendances à chaque fois.

L'installation du thème lui-même et de ses dépendances est aussi simple qu'un...

pip install pyodide-mkdocs-theme

5. Modifier le fichier `mkdocs.yml`#

Voici ci-dessous une comparaison des sections que vous devriez trouver dans votre fichier actuel, avec ce par quoi elles devraient être remplacées après installation du thème.

Toutes les options/items qui apparaissent dans votre fichier d'origine et qui ne sont pas mentionnés ci-dessous doivent être conservés.

Modifications pour la section theme :

AvantAprès

theme:
    name: material

    custom_dir: my_theme_customizations

    font: false
    language: fr

    palette:
        - media: "(prefers-color-scheme: light)"
        scheme: slate
        primary: dark blue
        accent: dark blue
        toggle:
            icon: material/weather-night
            name: Passer au mode jour
        - media: "(prefers-color-scheme: dark)"
        scheme: default
        primary: dark blue
        accent: dark blue
        toggle:
            icon: material/weather-sunny
            name: Passer au mode nuit

    features:
        - navigation.instant

theme:
    name: pyodide-mkdocs-theme

#   features:
#       - navigation.instant    # /!\ ceci est INCOMPATIBLE avec le thème

La palette de couleur est maintenant intégrée par défaut au thème.
Si vous souhaitez en changer, vous pouvez redéclarer la section entière et vos réglages prendront le pas sur les valeurs par défaut.
Mêmes choses pour la langue et la suppression des google-fonts (non RGPD).
La désactivation de navigation.instant est nécessaire car son fonctionnement est devenu incompatible avec l'environnement des ACE-editor, suite à la MAJ de material vers sa version 9⁺.
Une conséquence indésirable de ceci est que l'environnement pyodide doit être rechargé à chaque chargement d'une page utilisant un terminal ou un IDE. Ceci implique des temps d'attente... Il est prévu de contourner cette limitation dans une mise à jour ultérieure du thème.

Modifications pour les plugins :

Là aussi, conservez tout réglage de votre fichier non discuté dans cette section.

Si vous avez des réglages particuliers concernant les macros, transférez-les sans modifications dans la section pyodide_macros, le plugin du thème étendant lui-même celui de mkdocs-macros-plugin (voir la note dans le panneau Après ci-dessous).

AvantAprès

plugins:
    - search
    - macros:
        on_error_fail: true   # Vous avez peut-être vos propres réglages, ici?
    - exclude:                # Si vous utilisiez mkdocs-exclude, vous devriez pouvoir
        ...                   # le supprimer en utilisant à la place `exclude_docs`.

plugins:
    - search
    - 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.

# En remplacement de mkdocs-exclude. Tous les fichiers correspondant aux patterns indiqués
# seront exclus 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

Le plugin pyodide_macros est installé avec le thème. Il contrôle les comportements des macros du thème et étend également les fonctionnalités de mkdocs-macros-plugin.
Si vous avez besoin d'ajouter vos propres macros au thème, ou de modifier certains comportements associés normalement au plugin mkdocs-macros-plugin, collez simplement vos réglages dans la section pyodide_macros.

Pièges à éviter lors de l'enregistrement d'autres plugins

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.

Modifications pour les markdown_extensions :

Il n'y a normalement pas de modifications à apporter à la section markdown_extensions.
Vérifiez simplement que toutes les extensions requises sont bien présentes dans votre projet.

6. Réincorporer vos personnalisations #

Les macros personnalisées :

Le plugin pyodide_macro "étend" le plugin mkdocs-macros-plugin et fonctionne donc exactement de la même façon, avec le même mode de déclaration des macros et les mêmes options dans le fichier mkdocs.yml (mais sous le nom de plugin pyodide_macros au lieu de macros).

Si vous n'avez pas supprimé le fichier main.py d'origine parce que vous y aviez ajouté vos macros personnalisées, vous devriez donc pouvoir le réutiliser directement avec le thème, à la seule condition de supprimer toutes les macros dont le nom correspond à une de celles définies dans le thème (Le tableau en haut de cette page indique les noms de macros existant dans le thème).

Voir aussi la page dédiée au fonctionnement des macros personnalisées, pour plus d'informations sur leur utilisation avec pyodide-mkdocs-theme.

Les fichiers de styles ou les scripts :

Placez ces fichiers dans docs/extras/ et référencer ces fichiers dans les sections extras_css et extra_javascript du fichier mkdocs.yml.

Cela devrait être suffisant pour retrouver la plupart de vos anciens réglages, mais pour ce qui concerne les règles css ou les recherches d'éléments dans le DOM, il est probable qui vous ayiez besoin de modifier des noms de classes/ids, si vous aviez personnalisé les IDEs, terminaux, ... : la structure du DOM autour de ces éléments a été totalement refondue et il vous faudra donc explorer la page et modifier vos règles en conséquence.

Personnalisations plus complexes :

Il peut être nécessaire de travailler avec un custom_dir pour réintégrer certaines personnalisations.

Notez également que le thème propose des "crochets" spécifiques pour insérer facilement de la logique personnalisée dans le fichier main.html du thème.

7. Mettre à jour les fichiers de la documentation #

Deux types de problèmes peuvent se poser à ce stade, lors d'un mkdocs serve ou d'un mkdocs build :

Le thème impose par défaut que les noms de dossiers et les fichiers .py et .md soient limités au jeu de caractères [a-zA-Z0-9_.-]+. Ceci permet de garantir le bon fonctionnement des IDE dans le site construit.

Si cette contrainte n'est pas respectée, une erreur est levée, et il faudrait donc que vous modifiiez les noms de fichiers et dossiers en question.

Si cela n'est pas envisageable (liens existants que vous ne souhaitez pas briser, par exemple) et que vous êtes sûrs que les noms que vous utilisez sont tout de même compatibles, vous pouvez désactiver cette vérification dans le fichier mkdocs.yml:
```
plugins:
    - pyodide_macros:
        build:
            skip_py_md_paths_names_validation: true
```
Utiliser des redirections, si besoin

Il est vivement déconseillé d'activer cette option, sauf le temps de faire la mise à jour vers le thème.

Si vous voulez absolument garder les anciennes adresses actives, il est toujours possible de mettre en place des redirections 301 vers les nouveaux noms de pages. Le plugin mkdocs-redirects permet de mettre en place ce type de redirections.

À noter que ce réglage permet de passer un mkdocs serve ou un build sans erreur, mais les IDEs seront probablement non fonctionnels, ou au moins certains d'entre eux. Ce n'est donc pas une solution pour éviter de faire la mise à jour de la documentation lors du passage au thème.

Le thème introduit diverses options de configuration relative aux ides, qui imposent certains contrats qui n'existaient pas dans pyodide-mkdocs. Selon la façon dont vous souhaitez utiliser les IDEs, vous pourriez vouloir désactiver certaines de ces options, notamment :

8. Annuler les réglages spécifiques à la mise à jour#

Une fois que tout marche à nouveau, ne pas oublier de supprimer les réglages temporaires.

plugins:
    - pyodide_macros:
        build:
            skip_py_md_paths_names_validation: false  # Supprimer cette ligne uniquement, ou toute
                                                      # la section `build` si c'est la seule option