diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/404.html b/404.html new file mode 100644 index 0000000..8d5cf6f --- /dev/null +++ b/404.html @@ -0,0 +1,325 @@ + + + +
+ + + + + + + + + + + +MkDocs est un générateur de sites statiques open source conçu pour créer et
+publier facilement de la documentation à partir de fichiers Markdown.
La configuration se fait via un fichier mkdocs.yml
qui définit la structure, les
+thèmes (intégrés ou personnalisés) et les options du site.
La génération automatique du site sur GitHub avec MkDocs repose sur
+l’utilisation de GitHub Actions, qui exécute un workflow défini dans un fichier
+de configuration situé dans le dossier .github/workflows
. Ce workflow
+automatise les étapes de récupération du code source, l’installation des
+dépendances nécessaires, la génération des fichiers statiques à partir des
+fichiers Markdown, puis leur déploiement sur la branche dédiée au site,
+généralement gh-pages
, utilisée par GitHub Pages pour servir le site web.
.github/
+ └── 📁 workflows/
+ └── 📝 main.yml # Fichier de configuration du workflow GitHub Actions
+docs/
+ 📁 Plus-info-Mkdocs/
+ ├── 📁 Images/ # Dossier contenant les images pour les guides
+ ├── 📝 1-github-pages.md # Guide sur l'utilisation de GitHub Pages avec MkDocs
+ ├── 📝 2-config-mkdoc.md # Instructions pour configurer MkDocs
+ ├── 📝 3-workflow.md # Workflow pour automatiser les tâches avec MkDocs
+ └── 📝 4-tips.md # Conseils pratiques pour MkDocs
+ 📝 index.md # Page principale ou table des matières du projet
+🛑 .gitignore # Liste des fichiers/dossiers exclus du contrôle de version Git
+⚙️ mkdocs.yml # Fichier de configuration principal pour MkDocs
+📖 README.md # Documentation principale du projet
+📋 requirements.txt # Liste des dépendances Python nécessaires pour le projet
+
Il suffit de lancer :
+mkdocs serve
+
% mkdocs serve
+INFO - Building documentation...
+INFO - [macros] - No default module `main` found
+PDF rendering is disabled in serve mode
+NFO - [macros] - Config variables: ['extra', 'config', 'environment', 'plugin', 'git', 'macros', 'filters', 'filters_builtin']
+INFO - [macros] - Config macros: ['context', 'macros_info', 'now', 'fix_url']
+INFO - [macros] - Config filters: ['pretty', 'relative_url']
+INFO - Cleaning site directory
+INFO - Documentation built in 0.23 seconds
+INFO - [16:03:01] Watching paths for changes: 'docs', 'mkdocs.yml'
+INFO - [16:03:01] Serving on http://127.0.0.1:8000/
+
Warning
+Il est possible qu'il faille installer plein +d"extensions avec `pip ou autre ;-)
++
Texte générés en partie par ChatGPT !
++
Texte générés en partie par ChatGPT !
+Push vers GitHub
+Lorsque vous effectuez un git push
vers une branche, les fichiers
+modifiés sont envoyés au dépôt distant. Cela déclenche les workflows
+configurés dans GitHub Actions si des événements correspondants sont
+définis (par exemple, sur push
).
Déclenchement du Workflow GitHub Actions
+GitHub détecte le push et exécute le fichier de workflow
+ défini dans .github/workflows/main.yml
.
Installation de l'environnement
+Dans un projet MkDocs, les étapes incluent :
+mkdocs-material
, etc.).Installation de l'environnement
+Dans un projet MkDocs, les étapes typiques incluent :
+mkdocs-material
, etc.).Génération des fichiers statiques
+Une fois l'environnement prêt, la commande mkdocs build
est
+ exécutée pour convertir les fichiers Markdown en pages HTML statiques, selon la configuration définie dans mkdocs.yml
.
Déploiement sur GitHub Pages
+Si la branche concernée est main
, la commande mkdocs gh-deploy
est exécutée :
gh-pages
.Mise à jour du site
+Après le déploiement sur gh-pages
, le site hébergé sur GitHub Pages
+ (par ex. https://inria.github.io/datalake/
) est automatiquement mis à jour avec les dernières modifications.
Notification et suivi
+GitHub affiche les logs du workflow dans l'onglet Actions, où vous pouvez + vérifier le succès ou l'échec des différentes étapes. En cas de problème + (ex. : erreur de configuration), vous recevez une notification pour corriger et pousser une mise à jour.
++
Texte générés en partie par ChatGPT !
+Par défaut, MkDocs génère le menu à partir de l'arborescence
+des fichiers dans docs/
, en triant les noms par ordre
+alphabétique et en utilisant les titres de niveau 1 (# Titre)
+des fichiers Markdown comme titres affichés. Si aucun titre
+n'est défini, le nom du fichier est utilisé comme titre.
Généralement, ce n'est pas ce que l'on souhaite.
+Nommer les fichiers de sorte qu'ils respectent l'ordre +souhaité (ici en mettant un numéro en début de fichier)
+Arborescence des fichiers Correspondence avec les titres
+ dans les fichiers
+
+docs/ Datalake DCIS
+├── index.md ├── Accueil
+└── More-about-Mkdocs/ └── Plus info MkDocs
+ ├── 1-github-pages.md ├── Génération du portail MkDocs
+ ├── 2-config-mkdoc.md ├── Extensions MkDocs
+ ├── 3-workflow.md ├── Workflow
+ └── 4-tips.md └── Tips
+
nav:
dans mkdocs.yml
¶Une autre solution possible est de modifier directement l'ordre +dans le fichier de configuration. +
nav:
+ - Accueil: index.md
+ - Plus info MkDocs:
+ - Génération du portail MkDocs: More-about-Mkdocs/1-github-pages.md
+ - Extensions MkDocs: More-about-Mkdocs/2-config-mkdoc.md
+ - Workflow: More-about-Mkdocs/3-workflow.md
+ - Tips: More-about-Mkdocs/4-tips.md
+
Pour afficher un dossier avec un titre différent dans le menu,
+la seule solution est d’utiliser la configuration nav
+dans mkdocs.yml
. Par exemple, pour un dossier
+nommé Plus-info-Mkdocs
et une entrée de menu intitulée
+« Plus d’infos sur MkDocs »,
+vous devez écrire :
nav:
+ - Plus d’infos sur MkDocs:
+ - Génération du portail: Plus-info-Mkdocs/1-github-pages.md
+ - Extensions: Plus-info-Mkdocs/2-config-mkdoc.md
+
Cela établit le lien entre le dossier réel et son alias dans le +menu. Cette méthode est nécessaire si vous avez plusieurs dossiers.
++
Texte générés en très grande partie par ChatGPT !
+\n {translation(\"search.result.term.missing\")}: {...missing}\n
\n }\n