Aller au contenu

Déployer la documentation sur Cloudflare Pages

Page de maintenance

Cette page concerne le déploiement de la documentation et n'est pas nécessaire pour utiliser le package.

Cette page décrit le déploiement automatique de la documentation MkDocs lorsque la branche main est poussée sur GitHub.

Principe

Cloudflare Pages peut être connecté à un dépôt GitHub. À chaque push sur la branche de production, Cloudflare exécute la commande de build, publie le dossier site, puis met à jour le site. Les branches et pull requests peuvent aussi produire des déploiements de prévisualisation.

Dans ce dépôt, la documentation vit dans le sous-dossier package-xyt-gps. Deux configurations sont possibles. La plus lisible est de déclarer package-xyt-gps comme root directory du projet Pages.

Configuration recommandée

Dans Cloudflare Pages :

Paramètre Valeur
Framework preset MkDocs ou None
Production branch main
Root directory package-xyt-gps
Build command python -m pip install -r requirements-docs.txt && python -m mkdocs build
Build output directory site
Variable d'environnement PYTHON_VERSION=3.12

Cette configuration installe uniquement les dépendances nécessaires à la documentation, puis construit le site statique.

Le dossier de sortie doit être site, sans slash initial. Avec un root directory package-xyt-gps, Cloudflare publie le dossier package-xyt-gps/site. Une valeur comme /site peut pointer au mauvais endroit.

La commande utilise python -m mkdocs build plutôt que mkdocs build parce que, dans l'environnement Cloudflare, le script mkdocs installé par pip peut ne pas être disponible dans le PATH alors que le module Python est bien installé.

Variante sans root directory

Si le projet Cloudflare Pages pointe sur la racine du dépôt, utiliser :

Paramètre Valeur
Production branch main
Build command cd package-xyt-gps && python -m pip install -r requirements-docs.txt && python -m mkdocs build
Build output directory package-xyt-gps/site
Variable d'environnement PYTHON_VERSION=3.12

Contrôle local avant push

Depuis package-xyt-gps :

python -m pip install -r requirements-docs.txt
python -m mkdocs build

Pour prévisualiser localement :

mkdocs serve

La documentation est ensuite disponible sur http://127.0.0.1:8000/.

Points de vigilance

  • Ne pas publier Data/, Data/Output/, Output/, ni les notebooks avec sorties de cellules.
  • Garder requirements-docs.txt léger : il sert seulement à construire la doc.
  • Mettre à jour la doc avant le push si l'API publique ou les notebooks Notebooks/Package-ready/ changent.
  • Vérifier que la branche de production est bien main.

Références