ADR-038 : Documentation des opt-ins embarquée par paquet¶

Statut¶

Accepté, Forge 1.0.0-beta.x (ticket ADR-OPTIN-DOCS-EMBED-001).

La décision de principe est prise.
Le module pilote forge-mvc-stats a prouvé la chaîne de build complète (ticket OPTIN-DOCS-EMBED-STATS-001, commit b6f18d5 : mkdocs build --strict vert, doc montée sous /stats/), sur le modèle séquencé de l'ADR-035.
La convention de slug d'URL ci-dessous est figée avant le déploiement aux onze autres opt-ins.

Date¶

2026-06-21

Contexte¶

Forge est distribué en plusieurs paquets PyPI : un cœur forge-mvc et douze briques opt-in (forge-mvc-mfa, forge-mvc-rbac, forge-mvc-workflow, forge-mvc-stats, forge-mvc-files, forge-mvc-images, forge-mvc-iot, forge-mvc-video, forge-mvc-audio, forge-mvc-mail, forge-mvc-pivot, forge-mvc-i18n).
Voir l'ADR-005 (packaging hybride monorepo plus multi-distributions) et l'ADR-004 (périmètre du core minimal).

Aujourd'hui, toute la documentation et tous les parcours welcome des opt-ins vivent dans le docs/ unique du cœur.
Chaque paquet dans packages/ ne porte qu'un README.md.
Le rangement actuel est de plus incohérent et brouille la frontière core / opt-in :

docs/iot/ et docs/video/ ont leur propre tronc de premier niveau ;
mais MFA, RBAC, Mail, Images sont dissous dans docs/features/, au même niveau que des pages strictement core (crud.md, relations.md, migrations.md) ;
la référence des opt-ins est éclatée dans docs/reference/ ;
les parcours sont dans docs/starters/welcome-*.

Trois problèmes en découlent :

Frontière core / opt-in invisible (principes 1 et 8).
Un lecteur ne peut pas distinguer ce qui est livré par forge-mvc de ce qui exige un pip install forge-mvc-xxx.
features/rbac.md (opt-in) et features/crud.md (core) sont indiscernables.
Rangement non uniforme (principe 11).
Deux opt-ins ont un tronc dédié, dix autres sont dispersés dans des sections core.
La charte impose une seule façon officielle de ranger chaque chose.
Couplage de distribution.
Un utilisateur qui installe seulement forge-mvc-mfa depuis PyPI ne reçoit qu'un mince README.md ; la vraie documentation est ailleurs, dans le dépôt du cœur.
Toute évolution ou suppression d'un opt-in oblige à éditer le docs/ du core.

Décision¶

Chaque paquet opt-in possède sa propre documentation, embarquée dans le paquet sous packages/<paquet>/docs/.
Le site MkDocs unique reste la façade publique : il agrège les arbres de documentation des paquets au moment du build, via un plugin d'agrégation (famille mkdocs-monorepo).

Concrètement :

Chaque opt-in expose un sous-arbre homogène : présentation, référence et parcours welcome, sous packages/<paquet>/docs/.
Le cœur docs/ ne documente plus que le cœur ; les pages opt-in en sont retirées.
Le README.md PyPI de chaque paquet pointe vers la page publiée de sa doc.
La navigation du site présente un tronc « Opt-ins officiels » qui rassemble les sous-arbres agrégés des douze paquets.

Le site reste unique : on ne fragmente pas en douze sites séparés.
Cela préserve la cohérence pédagogique (les parcours renvoient au cœur) et le choix monorepo de l'ADR-005.
L'agrégation rétablit en revanche la séparation physique et de distribution : le paquet embarque et versionne sa propre doc.

Convention de slug d'URL (figée)¶

Le plugin d'agrégation utilise le site_name du sous-mkdocs.yml comme préfixe d'URL : la doc d'un opt-in est montée sous /<slug>/.
Le choix du slug est donc une décision de surface publique, figée ici avant le déploiement.

Règle : le slug d'un opt-in est le nom du paquet PyPI privé de son préfixe forge-mvc-.

Paquet	Slug	Racine d'URL
`forge-mvc-stats`	`stats`	`/stats/…`
`forge-mvc-workflow`	`workflow`	`/workflow/…`
`forge-mvc-mfa`	`mfa`	`/mfa/…`
`forge-mvc-rbac`	`rbac`	`/rbac/…`
`forge-mvc-files`	`files`	`/files/…`
`forge-mvc-images`	`images`	`/images/…`
`forge-mvc-iot`	`iot`	`/iot/…`
`forge-mvc-video`	`video`	`/video/…`
`forge-mvc-audio`	`audio`	`/audio/…`
`forge-mvc-mail`	`mail`	`/mail/…`
`forge-mvc-pivot`	`pivot`	`/pivot/…`
`forge-mvc-i18n`	`i18n`	`/i18n/…`

Justification :

court et lisible (/stats/welcome/installation/ plutôt que /forge-mvc-stats/welcome/installation/) ;
sans ambiguïté dans le contexte du site (le slug nomme la brique) ;
unique : aucun slug n'entre en collision avec un dossier de premier niveau du cœur (reference, features, guide, install…).
Les slugs iot et video reprennent à l'identique les anciens troncs docs/iot/ et docs/video/, qui sont migrés dans les paquets : l'URL publique ne change pas pour ces deux modules.

Sous-arborescence interne d'un opt-in (figée pour l'homogénéité) :

reference.md : page de référence, montée en /<slug>/reference/ ;
welcome/ : parcours pédagogique, monté en /<slug>/welcome/…, en conservant la profondeur welcome/<niveau>/<palier>.md pour préserver les liens relatifs vers le cœur (voir « Liens relatifs » ci-dessous).

Note d'implémentation : l'!include doit être déclaré avec une clé (- Titre: '!include packages/<paquet>/mkdocs.yml').
La forme en item nu est ignorée par le merger du plugin (les pages sont préfixées dans la nav mais leurs fichiers ne sont pas agrégés).

Pré-requis anti-casse : valider la chaîne de build, puis migrer par paliers¶

Deux risques techniques interdisaient une bascule en bloc ; le pilote stats les a levés.

Compatibilité du plugin d'agrégation.
mkdocs-monorepo-plugin (déclaré dans requirements-docs.txt et requirements-dev.txt) cohabite avec mkdocs-material, le plugin search (langue fr), glightbox et les extensions Markdown actives, et passe mkdocs build --strict (validé par le pilote, 0 avertissement).
Liens relatifs.
Les parcours welcome opt-in contiennent environ 361 liens relatifs ../.
Le pilote a montré qu'en conservant la profondeur d'arborescence (<slug>/welcome/<niveau>/ aussi profond que l'ancien starters/welcome-<m>/<niveau>/), la quasi-totalité des liens sortants vers le cœur restent valides sans réécriture ; seuls les liens entrants (depuis le cœur vers la doc migrée) et le lien « vue d'ensemble des starters » sont à recâbler.

Ordre d'exécution :

Outiller (fait) : dépendance de build ajoutée, plugin branché dans mkdocs.yml.
Piloter (fait) : forge-mvc-stats migré, mkdocs build --strict vert.
Généraliser : un paquet par ticket, en appliquant la convention de slug et la sous-arborescence figées ci-dessus.
Nettoyer les pages opt-in résiduelles dans le docs/ du cœur et les références croisées.

Aucune suppression dans le docs/ du cœur n'a lieu avant que le sous-arbre correspondant ne soit servi par l'agrégation.

Dettes à généraliser pendant le déploiement :

tests/meta/test_docs_forge_2x_sweep_001.py ne balaie que docs/ ; étendre le balayage à packages/*/docs/ pour que les docs migrées restent couvertes.
Le hub docs/starters/index.md pointera de plus en plus dans les arbres montés ; à terme, un tronc de navigation « Opt-ins officiels » dédié.

Conséquences¶

Positives :

Frontière core / opt-in nette, dans la navigation et sur le disque (principes 1 et 8).
Rangement uniforme des douze opt-ins (principe 11).
Le paquet embarque et versionne sa doc ; le README.md PyPI y pointe.
Le cœur est découplé : ajouter ou retirer un opt-in ne touche plus le docs/ du core.

Négatives / coûts :

Dépendance de build supplémentaire (plugin d'agrégation) et machinerie mkdocs.yml à maintenir.
Effort de migration : déplacement des arbres et réécriture d'environ 361 liens relatifs.
Risque de compatibilité du plugin avec le thème et les extensions, à lever par le pilote.

ADR liés¶

Précise l'ADR-005 (packaging hybride monorepo) : la documentation suit la frontière de distribution déjà actée pour le code.
Sert les ADR-004 et 016 (périmètre du core minimal, modèle opt-in) en rendant la frontière visible dans la documentation.
N'affecte pas l'ADR-035 (parcours manuels) : les parcours welcome restent manuels ; seul leur emplacement change.

Charte appliquée¶

Principe 1 : séparer framework et briques (la doc suit la séparation du code).
Principe 8 : noyau minimal, briques opt-in (le cœur ne documente que le cœur).
Principe 11 : une seule façon officielle de ranger la doc d'un opt-in.
Principe 6 : tester avant d'élargir (pilote obligatoire avant généralisation).
Règle A : retirer la cause (la doc opt-in logée dans le cœur), pas le symptôme (le rangement incohérent actuel).