Aller au contenu

Déployer la documentation

La documentation MkDocs peut être déployée comme site statique depuis Git avec Cloudflare Pages.

Principe

Cloudflare Pages lit le dépôt Git, installe les dépendances nécessaires au build de la documentation, exécute mkdocs build, puis publie le dossier site/.

Le dépôt ne doit pas contenir les données GPS ni les outputs lourds. Seuls les fichiers de documentation, de configuration et de code nécessaires au build sont poussés.

Réglages Cloudflare Pages

Dans Cloudflare :

  1. ouvrir Workers & Pages ;
  2. créer une application Pages ;
  3. importer le dépôt GitHub action-situee/parking_cruising ;
  4. choisir la branche de production ;
  5. renseigner les paramètres de build.

Réglages recommandés :

Paramètre Valeur
Production branch main
Framework preset aucun ou MkDocs si proposé
Build command python -m pip install -r requirements-docs.txt && mkdocs build --clean --strict
Build output directory site
Root directory vide, donc racine du dépôt
Environment variable PYTHON_VERSION=3.10.18 ou 3.10

La branche marced peut être utilisée pour les previews. La branche main doit rester la branche de production si l'objectif est d'avoir une URL stable.

Pourquoi requirements-docs.txt

Le fichier requirements.txt sert au pipeline complet. Il contient notamment TensorFlow/Keras, JupyterLab et des dépendances d'analyse qui ne sont pas toutes nécessaires au build du site.

Le fichier requirements-docs.txt est dédié à Cloudflare Pages. Il contient :

  • MkDocs et ses plugins ;
  • les dépendances nécessaires à mkdocstrings, car la page API importe les modules Python locaux ;
  • les dépendances géospatiales importées par ces modules.

Il exclut TensorFlow/Keras pour limiter le temps de build. Le modèle ReLUT n'est pas exécuté pendant le build documentaire.

Workflow Git recommandé

git checkout marced
git status --short
git add .
git commit -m "Clarifier documentation et quickstart"
git push origin marced

Puis, pour passer en production :

git checkout main
git pull origin main
git merge marced
git push origin main

Alternative plus contrôlée : ouvrir une pull request marced vers main. Cloudflare Pages pourra générer une preview pour la branche ou la pull request, puis publier la production après merge sur main.

Vérifier localement avant push

source .venv-parking-search/bin/activate
mkdocs build --clean --strict

Si le build local échoue, corriger la documentation avant de pousser. Cloudflare exécutera le même build.

Points de vigilance

  • Ne pas pousser Data/GPS/, Output/, External/ ou site/.
  • Vérifier que .gitignore exclut les données, outputs, caches et fichiers lourds.
  • Ne pas placer de clé API ou de secret dans mkdocs.yml, docs/ ou les notebooks.
  • Si le build Cloudflare échoue sur une dépendance géospatiale, vérifier le log d'installation Python et la version PYTHON_VERSION.
  • Si la page API n'est pas nécessaire en ligne, elle peut être retirée de la navigation pour réduire les dépendances du build.