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 champs site_name et site_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.md et docs/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.html
copyright.html
footer.html
header.html
social.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
                SHOW: ""
                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
                SHOW: ""
                MERMAID: false
                AUTO_RUN: false
                TERM_H: 10
                FILL: ""

            py_btn:
                SANS: ""
                WHITE: ""
                REC_LIMIT: -1
                SHOW: ""
                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
                SHOW: ""
                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
                SHOW: ""

            figure:
                div_id: "figure1"
                div_class: ""
                inner_text: "Votre tracé sera ici"
                admo_kind: "!!!"
                admo_class: "tip"
                admo_title: "Votre figure"
                p5_buttons: null
                SHOW: ""

        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

    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 :

content.html
copyright.html
footer.html
header.html
social.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.md ou mon_fichier.md (le second cas ayant un comportement à part pour certaines opérations, lorsque use_directory_urls vaut true).

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é.

Installation

Installation via pip #

Démarrer un nouveau projet#

Dépendances #

mkdocs.yml : réglages #

Configuration par défaut pour le thème#

Configuration du fichier#

Changer la palette de couleurs#

Configuration du plugin du thème, pyodide_macros#

Plugins : pièges à éviter#

L'option use_directory_urls#

`mkdocs.yml` : réglages #

Configuration du plugin du thème, `pyodide_macros`#

L'option `use_directory_urls`#