Aller au contenu

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 :

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 dépôt reste privé. Le workflow publie uniquement le contenu génère 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 ;
  • exécution manuelle via workflow_dispatch.

Chemins surveilles :

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

Etapes :

  1. checkout du dépôt ;
  2. installation de Python 3.12 ;
  3. installation des dependances documentaires ;
  4. build strict MkDocs ;
  5. validation du répertoire Hostinger cible ;
  6. déploiement 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 être 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 vérifie que cette variable existe et se termine par / avant de lancer le déploiement 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 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 :

  1. modifier les fichiers Markdown dans docs/ ;
  2. mettre à jour mkdocs.yml si une page est ajoutée ;
  3. vérifier qu'aucun secret n'est présent ;
  4. lancer le build local si MkDocs est disponible ;
  5. committer ;
  6. merger vers main ;
  7. vérifier l'exécution GitHub Actions ;
  8. 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 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-slate sans vérifier le répertoire cible Hostinger, pour éviter 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 à jour site_url dans mkdocs.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.