Maarch Courrier Documentation
Documentation de Maarch Courrier écrite en Markdown, convertie en HTML avec mkdocs-material.
Pré-requis
- python3
- pip
- weasyprint (pour la conversion PDF)
- git
Installer les dépendances python :
python3 -m pip install mkdocs mkdocs-material mkdocs-with-pdf mkdocs-git-revision-date-localized-plugin
Construire la documentation en local
python3 -m mkdocs build --strict
Construire la documentation en mode développement
python3 -m mkdocs serve
La documentation sera disponible à l'adresse http://localhost:8000.
La documentation sera automatiquement rafraichi à chaque modification des pages .md.
Build avec la version PDF
Le build de la documentation en PDF est assez long, donc ce build est activé uniquement dans la génération en CI.
Pour obtenir le PDF en local, il faut mettre la variable d'environnement ENABLE_PDF_EXPORT à 1 :
export ENABLE_PDF_EXPORT=1
python3 -m mkdocs build --strict
Vérification des liens
La vérification stricte des liens (mkdocs build --strict) doit être réalisée uniquement pour la documentation web (HTML), et pas pour la génération PDF.
Pourquoi ?
Lors de l’export PDF (plugin mkdocs-with-pdf), les pages HTML sont assemblées et certains liens internes peuvent être réécrits sous forme d’ancres (#...) pour fonctionner à l’intérieur du PDF.
Or, les liens vers des fichiers téléchargeables (ex. .jks, .p12, .jar, .docx, .xml, .pdf) ne sont pas des pages : ils n’ont pas d’ancre correspondante dans le document PDF. Le plugin peut donc les signaler comme “missing links” même si les fichiers existent bien dans docs/ et sont accessibles sur le site web.
Exemple
Dans la documentation web, ces liens sont valides (les fichiers sont servis tels quels) :
[demo.jks](uploads/iparapheur/demo.jks)
[demo.p12](uploads/iparapheur/demo.p12)
En mode PDF, ces liens peuvent être interprétés comme des références internes au PDF et être listés comme manquants, car un fichier .jks ou .p12 n’est pas une page HTML.
Commande recommandée (vérification web uniquement)
Pour vérifier les liens de la documentation web, lancer le build sans activer le PDF (donc sans ENABLE_PDF_EXPORT) :
unset ENABLE_PDF_EXPORT
mkdocs build --strict --clean --config-file mkdocs.yml
Critère de validation
Si la commande ci-dessus ne remonte aucune erreur de liens et que le seul message restant est :
WARNING - without generate PDF(set environment variable ENABLE_PDF_EXPORT to 1 to enable)
Alors, on considère que la vérification des liens web est OK.
Mode Docker
Génération de l'image de dévopopement :
docker build -t local/courrier-doc .
Lancer l'environnement de développement :
docker compose -f compose.yml up -d
Acccès à l'interface de la documentation :
Le container est lié à votre projet local, les modifications effectuées seront prises en compte depuis cette adresse
Il est fortement conseillé de faire l'astuce du "Build plus rapide en local" pour avoir les modifications en temps réel