Module Publication documentation¶
Objectif¶
Le module Publication documentation rend la documentation technique accessible publiquement sans rendre le dépôt GitHub public et sans utiliser GitHub Pages.
La documentation est publiee comme site statique MkDocs sur Hostinger.
URL officielle :
Vue d'ensemble architecture¶
Depot prive GitHub
|
| push sur main ou workflow_dispatch
v
GitHub Actions
- installe Python
- installe MkDocs Material
- execute mkdocs build --strict
|
| FTP
v
Hostinger
- dossier statique publie
- domaine docs.solutravo-app.fr
Le dépôt reste privé. Le workflow publie uniquement le contenu génère dans site/.
Fichiers responsables¶
docs/ contient la source Markdown.
mkdocs.yml declare :
- le nom du site ;
- l'URL publique ;
- le theme Material ;
- les extensions Markdown ;
- la navigation.
requirements-docs.txt verrouille la dependance :
.github/workflows/docs.yml construit et deploie le site.
Workflow de publication¶
Nom :
Declencheurs :
- push sur
mainsi un fichier documentaire change ; - exécution manuelle via
workflow_dispatch.
Chemins surveilles :
Etapes :
- checkout du dépôt ;
- installation de Python
3.12; - installation des dependances documentaires ;
- build strict MkDocs ;
- validation du répertoire Hostinger cible ;
- déploiement FTP du dossier
site/.
Commande de build :
Le mode strict est volontaire : un lien casse ou une page absente doit bloquer la publication.
Configuration GitHub Actions¶
Secrets requis¶
Configurer dans GitHub Actions :
Ces valeurs ne doivent jamais être commitees.
Variable requise¶
Configurer aussi :
Cette variable doit finir par /.
Exemples possibles selon la configuration Hostinger :
Le workflow vérifie que cette variable existe et se termine par / avant de lancer le déploiement FTP.
Cible Hostinger¶
Hostinger doit exposer le domaine :
La racine web du domaine doit correspondre a DOCS_FTP_SERVER_DIR.
Le workflow utilise :
Il ne deploie donc pas le code source PHP, les workflows, le dépôt Git ou les fichiers Markdown bruts : uniquement le site statique génère.
Règles de contenu public¶
La documentation est publique. Elle peut contenir :
- noms de fichiers ;
- noms de classes ;
- routes ;
- tables ;
- colonnes ;
- variables d'environnement sans valeur ;
- flux techniques ;
- risques et points d'attention.
Elle ne doit pas contenir :
- mots de passe ;
- tokens ;
- clés API ;
- secrets FTP ;
- données client ;
- valeurs réelles d'environnements sensibles ;
- informations d'infrastructure plus precises que nécessaire.
mise à jour de la documentation¶
Flux recommande :
- modifier les fichiers Markdown dans
docs/; - mettre à jour
mkdocs.ymlsi une page est ajoutée ; - vérifier qu'aucun secret n'est présent ;
- lancer le build local si MkDocs est disponible ;
- committer ;
- merger vers
main; - vérifier l'exécution GitHub Actions ;
- ouvrir
https://docs.solutravo-app.fr.
Verification locale¶
Si MkDocs est installe :
ou :
Si MkDocs n'est pas installe localement :
Points d'attention pour reprise¶
- Ne pas utiliser GitHub Pages pour ce dépôt privé si l'objectif est d'éviter l'offre payante.
- Ne pas déployer la racine du repo sur le sous-domaine documentation. Seul
site/doit être publie. - Ne pas activer
dangerous-clean-slatesans vérifier le répertoire cible Hostinger, pour éviter d'effacer un dossier non documentaire. - Garder
mkdocs build --strictdans le workflow : c'est la garde principale contre les liens casses. - Si l'URL publique change, mettre à jour
site_urldansmkdocs.yml, cette page et l'ADR de publication. - Si la documentation doit devenir privée plus tard, ajouter une protection HTTP côté Hostinger plutôt que rendre le dépôt public.