Le site de documentation pour l'inventaire des orgues.
Une documentation sur Markdown
La documentation est générée depuis Markdown en HTML à l'aide de l'utilitaire Python de génération de site statiques Mkdocs (https://www.mkdocs.org)
Pour générer le site de documentation avec Mkdocs et éventuellement lancer le serveur local :
- installer le module mkdocs avec pip
- construire le site statique :
a- soit depuis une console, via la ligne de commande
mkdocs buildb- soit directement depuis Python via un script de lancementgenerate.pyadapté depuis un exemple trouvé sur le web
Le fichier de configuration, en langage yaml, peut-être personnalisé.
Lors d'un push sur le dépôt Github, une Action Github déploie automatiquement la documentation sur le serveur de l'inventaire des orgues :
- les sources en format Markdown sont copiées sur ce serveur,
- la documentation est immédiatement regénérée,
- les fichiers HTML déployés et le serveur Nginx redémarré.
Causes d'échec du déploiement automatique déjà rencontrées :
- une erreur d'encodage peut mettre en echec la commande
mkdocs build - il y a pu avoir désynchronisation du dépôt Git du serveur en cas de modification directement dessus. Solution :
git fetch --allgit reset --hard github_inventairedesorgues/mastergit pull github_inventairedesorgues mastermkdocs build
Initialement, ce site avait été mis en place par Bastien Guerry à l'aide de :
- module Org mode pour l'éditeur EMACS (https://github.com/fniessen/refcard-org-mode)
- modèle ReadTheOrg (https://github.com/fniessen/org-html-themes)
Le fichiers .org ont pour ce faire été convertis en fichiers Markdown .md façon Github Flavored Markdown (style gfm)(https://pandoc.org/MANUAL.html#atx-style-headings), à l'aide de l'outil Pandoc (https://pandoc.org).
./pandoc --from org --to gfm -o ido-docs/donnees.md ido-docs/donnees.org