Automatiser le build de la doc

Brancher le rebuild de la doc sur les événements Git, façon Read the Docs : événement → règles déclaratives → action, avec un garde-fou « un seul build par événement ».

Les règles

Elles vivent dans automation.yaml — modèle trigger × match × action :

first_match_only: true            # 1 seul build par événement
rules:
  - name: build-on-docs-change
    trigger: push
    match: { files: ["docs/**", "**/SKILL.md", "src/bfev/**"] }
    action: build
  - name: publish-on-tag
    trigger: tag
    match: { name: "v*" }
    action: [build, publish, set-default]

• trigger : push | tag | pull_request.
• match : files (globs, ** = n'importe quel sous-chemin) et/ou name (pour un tag).
• action : build (rend le site) ; publish (enregistre la version) ; set-default (redirige la racine) ; hide (rétention) ; notify (transport non configuré, Phase 5).
• retention (clé racine) : nombre de versions visibles gardées ; au-delà, les plus anciennes passent en archivées.

Lancer manuellement

python docs/run_automation.py --dry-run                      # montre la règle/les actions
python docs/run_automation.py --trigger push --files docs/index.md
python docs/run_automation.py --trigger tag --tag v0.2.0
python docs/run_automation.py                                # auto-détecte l'événement Git

Sans --trigger, le moteur déduit l'événement : un tag exact sur HEAD ⇒ tag ; sinon push avec les fichiers du dernier commit.

Brancher sur un hook Git

cp docs/hooks/post-commit .git/hooks/ && chmod +x .git/hooks/post-commit

Désormais chaque commit qui touche docs/, un SKILL.md ou src/bfev/ régénère le site — une seule fois (first_match_only), même si plusieurs règles pourraient matcher.

En CI

Même commande dans un job : python docs/run_automation.py --trigger push --files $(git diff --name-only HEAD~1 HEAD), ou sur tag pour publier.

Versionner & prévisualiser une PR

Le versionnement vit sous _site/ : chaque tag est figé dans son sous-dossier, la version par défaut redirige depuis la racine, un versions.html liste tout.

python docs/build_docs.py --version v0.2.0   # fige la doc sous _site/v0.2.0/
python docs/build_docs.py --pr 7             # prévisualise une PR sous _site/_pr-7/
python docs/run_automation.py --pr 7         # idem, via le moteur

Sur un tag vX, la chaîne publish-on-tag enchaîne automatiquement : build (→ _site/<tag>/) → publish (enregistre dans versions.json) → set-default (écrit la redirection racine) → hide (applique la rétention). Deux tags successifs coexistent dans _site/ ; le sélecteur versions.html les liste, les plus anciennes au-delà de la rétention en « archivées ».