Module Publication documentation¶

Objectif¶

Le module Publication documentation rend la documentation technique accessible publiquement sans rendre le depot GitHub public et sans utiliser GitHub Pages.

La documentation est publiee comme site statique MkDocs sur Hostinger.

URL officielle :

https://docs.solutravo-app.fr

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 depot reste prive. Le workflow publie uniquement le contenu genere dans site/.

Fichiers responsables¶

mkdocs.yml
requirements-docs.txt
.github/workflows/docs.yml
docs/

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 :

mkdocs-material==9.5.49

.github/workflows/docs.yml construit et deploie le site.

Workflow de publication¶

Nom :

Publish technical documentation to Hostinger

Declencheurs :

push sur main si un fichier documentaire change ;
execution manuelle via workflow_dispatch.

Chemins surveilles :

docs/**
mkdocs.yml
requirements-docs.txt
.github/workflows/docs.yml

Etapes :

checkout du depot ;
installation de Python 3.12 ;
installation des dependances documentaires ;
build strict MkDocs ;
validation du repertoire Hostinger cible ;
deploiement FTP du dossier site/.

Commande de build :

mkdocs build --strict

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 :

HOSTINGER_DOCS_FTP_HOST
HOSTINGER_DOCS_FTP_USERNAME
HOSTINGER_DOCS_FTP_PASSWORD

Ces valeurs ne doivent jamais etre commitees.

Variable requise¶

Configurer aussi :

DOCS_FTP_SERVER_DIR

Cette variable doit finir par /.

Exemples possibles selon la configuration Hostinger :

/
public_html/
domains/docs.solutravo-app.fr/public_html/

Le workflow verifie que cette variable existe et se termine par / avant de lancer le deploiement FTP.

Cible Hostinger¶

Hostinger doit exposer le domaine :

docs.solutravo-app.fr

La racine web du domaine doit correspondre a DOCS_FTP_SERVER_DIR.

Le workflow utilise :

local-dir: ./site/
server-dir: ${{ vars.DOCS_FTP_SERVER_DIR }}

Il ne deploie donc pas le code source PHP, les workflows, le depot Git ou les fichiers Markdown bruts : uniquement le site statique genere.

Regles 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 ;
cles API ;
secrets FTP ;
donnees client ;
valeurs reelles d'environnements sensibles ;
informations d'infrastructure plus precises que necessaire.

Mise a jour de la documentation¶

Flux recommande :

modifier les fichiers Markdown dans docs/ ;
mettre a jour mkdocs.yml si une page est ajoutee ;
verifier qu'aucun secret n'est present ;
lancer le build local si MkDocs est disponible ;
committer ;
merger vers main ;
verifier l'execution GitHub Actions ;
ouvrir https://docs.solutravo-app.fr.

Verification locale¶

Si MkDocs est installe :

python3 -m mkdocs build --strict

ou :

mkdocs build --strict

Si MkDocs n'est pas installe localement :

python3 -m pip install -r requirements-docs.txt
python3 -m mkdocs build --strict

Points d'attention pour reprise¶

Ne pas utiliser GitHub Pages pour ce depot prive si l'objectif est d'eviter l'offre payante.
Ne pas deployer la racine du repo sur le sous-domaine documentation. Seul site/ doit etre publie.
Ne pas activer dangerous-clean-slate sans verifier le repertoire cible Hostinger, pour eviter d'effacer un dossier non documentaire.
Garder mkdocs build --strict dans le workflow : c'est la garde principale contre les liens casses.
Si l'URL publique change, mettre a jour site_url dans mkdocs.yml, cette page et l'ADR de publication.
Si la documentation doit devenir privee plus tard, ajouter une protection HTTP cote Hostinger plutot que rendre le depot public.