Débuter avec MkDocs

Auteur : Franck CHAMBON

Objectifs

1. Introduction à Markdown pour son utilisation
   • avec Jupyter, pour créer des carnets,
   • avec CodiMD, pour du travail collaboratif,
   • avec MkDocs, pour participer ou créer de la documentation comme celle-ci.
2. Présentation des premiers pas pour héberger un site web statique avec MkDocs for Material, sur GitLab en particulier.

À l'instar de cette page, il y a quelques éléments dynamiques et la construction est assez élémentaire pour être proposée

• aux élèves en SNT, pour un travail en local,
• aux élèves en NSI, pour la documentation de projet,
• aux collègues enseignants pour du travail collaboratif.

Pourquoi MkDocs ?

MkDocs permet de générer de la documentation autour de l'écosystème Markdown et Python.

• C'est un logiciel libre reconnu pour sa qualité et très utilisé. https://github.com/mkdocs/mkdocs/

Prérequis

Définitions

Par machine, on entend PC, smartphone ou tablette Android. On peut créer ou mettre à jour ce genre de site depuis n'importe quel type de machine qui a accès à Internet.

Par PC, on entend un ordinateur avec un système d'exploitation Windows, Mac ou Linux.

Pour Linux, on prendra l'exemple d'une distribution basée sur les paquets debian, sinon vous devriez savoir adapter ce qui suit sans difficulté.

Machine raisonnablement à jour

Android

Passer en mode développeur

• Accéder à Paramètres de l’appareil Android
• Aller dans les paramètres Système
• Aller dans À propos du téléphone
• Tapoter 7 fois Numéro de build
• C'est fait !

Mises à jour

1. Installer F-Droid.
2. À partir de F-Droid, installer Termux
3. Dans Termux, entrer

   $ apt update
   $ apt upgrade
   $ apt install python
   $ pip install --upgrade pip
   

Linux

Administration

Mettre à jour via une interface graphique, ou bien dans un terminal avec

$ sudo apt update
$ sudo apt upgrade
$ sudo dpkg --configure -a

Gestionnaire de paquets Python

pip est le gestionnaire de paquets Python, suivant votre machine la commande est pip ou pip3.

Dans la suite on la désignera par pip,

• Si c'est pip3 ; adapter.

Vérifier (cf infra) la présente de pip ou pip3, et l'installer le cas échéant

Installation de pip

$ sudo apt install python3-pip

Redémarrer alors, pour que le PATH inclut bien votre chemin de binaires, même si c'est probablement déjà le cas...

Mises à jour de pip

Dans un terminal entrer

$ sudo -H pip install --upgrade pip

Mac

Administration

Mettre à jour le système via les update proposées.

Gestionnaire de paquets Python

pip est le gestionnaire de paquets Python, suivant votre machine la commande est pip ou pip3.

Dans la suite on la désignera par pip,

• Si c'est pip3 ; adapter.

Vérifier (cf infra) la présente de pip ou pip3, et l'installer le cas échéant

Installation de pip

$ sudo apt install python3-pip

Redémarrer alors, pour que le PATH inclut bien votre chemin de binaires, même si c'est probablement déjà le cas...

Mises à jour de pip

Dans un terminal entrer

$ pip install --upgrade pip

Windows

Administration

Suivez les mises à jour indiquées.

Pour l'installation de Python que vous avez réalisée, il faut bien avoir coché la case « Inclure Python dans le PATH »

Pour mettre à jour pip, entrer > python -m pip install --upgrade pip

• Si une erreur se produit, c'est que vous n'avez pas pip d'installé. Pour l'installer,
  • télécharger get-pip.py,
  • entrer > python get-pip.py dans le dossier où vous avez le script téléchargé.

Mises à jour de pip

Dans un terminal entrer

$ python -m pip install --upgrade pip

Et Jupyter ?

On suppose que

• vous avez déjà Jupyter installé, ou que
• vous utilisez Capytale avec des carnets Basthon, ou que
• vous utilisez Try Jupyter.

Installation

Vérification

Vérifier votre installation suivant votre machine avec

python / pip

$ python --version
Python 3.8.5
$ pip --version
pip 21.0.1 from .../lib/python3.8/site-packages/pip (python 3.8)

python3 / pip3

$ python3 --version
Python 3.8.5
$ pip3 --version
pip 21.0.1 from .../lib/python3.8/site-packages/pip (python 3.8)

Si une erreur survient, contacter l'administrateur de la machine.

Material for MkDocs

Dans un terminal, avec pip ou pip3 selon votre machine.

python / pip

$ pip install mkdocs-material

python3 / pip3

$ pip3 install mkdocs-material

Cela installe automatiquement plusieurs paquets utiles.

No module named 'materialx'

Dans de rares cas, il est utile d'ajouter la dépendance suivante (qui aurait dû s'installer automatiquement)

$ pip install mkdocs-material-extensions

Créer un nouveau MkDocs

Votre expérience

Créer un dossier que vous pouvez nommer experience1, par exemple.

Ouvrir un terminal dans ce dossier vide.

$ mkdocs new .

. désigne le dossier courant.

Vérification

Vous devriez avoir eu le message correspondant suivant

INFO    -  Creating project directory: expérience
INFO    -  Writing config file: experience1/mkdocs.ym
INFO    -  Writing initial docs: experience1/docs/index.md

Suivi en direct

Au programme

Nous allons construire un site web, d'abord en local sur votre machine.

On pourra le consulter depuis le navigateur Internet.

À chaque modification d'un fichier, le site sera mis à jour.

Construction à la volée

Dans un terminal, toujours dans ce même dossier, entrer

$ mkdocs serve

Victoire ?

Vous aurez une sortie qui ressemble à

INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
INFO    -  Documentation built in 0.07 seconds 
[I 210422 09:39:37 server:335] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000
[I 210422 09:39:37 handlers:62] Start watching changes
INFO    -  Start watching changes

Échec ?

Si vous avez une sortie qui ressemble à

INFO    -  Building documentation... 

Config file '...experience1/docs/mkdocs.yml' does not exist.

C'est que vous avez lancé la commande dans le mauvais dossier.

Visionnage en direct

Ouvrir votre navigateur Web à l'adresse indiquée.

Astuce : Mettre ce lien http://127.0.0.1:8000/ dans les marque-pages ; vous y reviendrez souvent .

Si vous avez un second écran, c'est le moment d'y placer cet onglet du navigateur

Modifions le site

Les fichiers dans le dossier ont pour l'instant cette architecture

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

Victoire

Avec un bon éditeur de texte, éditer le fichier docs/index.md

Voici ce qu'on peut faire.

Avec pour résultat.

À chaque fois qu'un fichier sera modifié et enregistré, le site sera mis à jour dans le navigateur.

Faîtes vos premières expériences !

Vous pourrez bientôt créer votre site comme celui-ci !!!

Votre site n'est pas encore construit physiquement

Il est possible de construire physiquement (en local) votre site avec

$ mkdocs build

C'est utile si vous avez une solution pour l'héberger ...

Pour nous ce sera inutile, on déléguera le travail.