ADR-145 — Documentation : un site, orientation par public ; Zola pour l’architecture, chaque langage à son outil natif

Statut : Accepté (2026-07-31, décision BDFL). RFC de mécanisme (ADR-015). Complète ADR-027 (stratégie de documentation polyglotte) en tranchant l’outillage de rendu, sans toucher à sa règle fondatrice : la documentation polyglotte est générée depuis les commentaires Rust, jamais rédigée en parallèle. S’appuie sur ADR-024 (règle des 80 %), ADR-025 (déterminisme, versions pinnées).

Catégorie : outillage de documentation (scripts/build-docs.sh, workflow docs).

Contexte

Ce que voit un développeur

https://docs.air-desktop.org sert des sous-sites d’apparences étrangères : /guide/ en mdBook, /api/ en rustdoc, /api-c/ en Doxygen. Trois architectures d’information, trois mises en page, trois recherches cloisonnées.

Le problème n’est pas l’existence de plusieurs générateurs — c’est qu’aucune règle ne dit qui va où, et pourquoi. Le développeur doit deviner.

Ce que mdBook ne permet pas

mdBook impose son propre gabarit HTML : on ne contrôle que le corps de la page. Impossible d’y placer un cartouche dans un vrai <header> de document, ni d’envelopper les rubriques d’un ADR dans de vraies <section>.

Or les ADR ont besoin des deux. Ils portent des métadonnées — numéro, date, statut de décision, avancement de mise en œuvre, langue — aujourd’hui noyées dans la prose, et une charpente canonique (Contexte, Décision, Conséquences) que rien ne rend visible ni ne fait respecter.

Ce qui a été mesuré

Une maquette Zola a été construite et publiée en parallèle sous /zola-maquette/, sur les mêmes ADR, pour comparer les deux rendus sur pièces plutôt que sur argument. Elle démontre le cartouche en <header>, les sections HTML5 réelles, et la distinction visible entre rubriques obligatoires et optionnelles.

Point technique validé au passage : en CommonMark, un bloc HTML se termine à la ligne vide. Le Markdown placé entre <section> et </section> reste interprété, ce qui permet d’envelopper les rubriques sans convertir soi-même le Markdown.

Décision

1. Un seul site, une orientation explicite par public

docs.air-desktop.org reste un seul site. Sa page d’accueil oriente explicitement chaque développeur vers l’outil natif de son langage — celui que sa communauté connaît et attend :

On ne cherche pas l’uniformité de rendu entre langages : on cherche que chacun se sente chez lui. Un développeur Rust veut rustdoc, pas une réinvention.

2. Doxygen est conservé, et étendu au C++

Contrairement à ce qu’envisageait un brouillon antérieur, Doxygen n’est pas retiré. Il traite déjà le C, il traitera le C++ le moment venu, et c’est un parseur C/C++ mûr qu’aucun générateur maison n’égalerait à coût raisonnable.

Écrire notre propre extracteur n’aurait été tenable que pour des bindings générés. Dès qu’une surface C++ écrite à la main existe, l’argument tombe. Conserver Doxygen évite d’avoir à re-décider plus tard.

3. Zola remplace mdBook pour la documentation d’architecture

Vision, charte, principes d’ingénierie, ADR et spécifications sont rendus par Zola — binaire Rust unique, sans dépendance de compilation, version pinnée.

Ce qu’il apporte et que mdBook ne peut pas donner :

• le contrôle complet du HTML5 par templates Tera : <header>, <section>, structure sémantique choisie ;
• un front-matter TOML par document, où loger les données du cartouche ;
• une feuille de style possédée, sans thème imposé.

4. Le gabarit d’ADR

Chaque ADR est rendu avec :

• un cartouche en <header> portant numéro, titre, objet, date de création, statut de décision (Accepté / Proposé), avancement de mise en œuvre et lien vers l’autre langue ;
• de vraies <section> portant une classe sémantique par rubrique ;
• une distinction visible entre rubriques obligatoires — Contexte, Décision, Conséquences — et optionnelles.

5. Aucune métadonnée recopiée

Le cartouche est calculé depuis docs/adrs/statuts.toml et l’en-tête du fichier ADR. Rien n’est saisi deux fois, donc rien ne peut diverger. Les fichiers ADR ne sont pas modifiés : ils restent la source.

6. Les deux langues sont publiées

SUMMARY.md publiait 144 ADR français et 2 anglais : les traductions existaient sans être servies. Le nouveau site publie les deux, et le cartouche porte le lien de l’une vers l’autre.

Conséquences

Positives.

• Chaque développeur trouve la documentation de son langage dans l’outil qu’il connaît, et sait où aller dès l’accueil.
• Les ADR gagnent un gabarit lisible, une charpente visible, et des métadonnées exploitables.
• Les 144 traductions anglaises deviennent enfin accessibles.
• Zola n’ajoute qu’un binaire, sans pile de compilation (ADR-024).

Négatives, assumées.

• La recherche est à réimplémenter. Zola produit l’index, pas l’interface — mdBook l’offrait gratuitement. C’est le principal coût caché de la bascule.
• Migration de tout docs/ : ADR, specs, notes, documents fondateurs. Un chantier bien plus large que la maquette.
• Un front-matter doit être dérivé pour chaque document. Scriptable, mais à éprouver — notamment sur les 18 ADR sans structure canonique et les 23 qui disent « Alternatives écartées » là où les autres disent « rejetées ».
• Deux générateurs de sites coexisteront pendant la migration.

Alternatives rejetées

A — Rester sur mdBook, avec un préprocesseur

Un préprocesseur mdBook injecterait le cartouche et envelopperait les sections.

Rejetée : on resterait locataire du gabarit. Le cartouche vivrait dans le corps de la page, pas dans un <header> de document, et la structure sémantique resterait subordonnée aux choix de mdBook. Moins coûteux, mais ne répond pas à l’exigence.

B — Un moteur unique ingérant tous les langages

Produire du JSON depuis rustdoc et du XML depuis Doxygen, puis tout rendre avec un seul moteur.

Rejetée : la sortie JSON de rustdoc est nightly-only et explicitement instable. Y adosser la documentation contredirait le Principe 8 (stabilité contractuelle). Et l’uniformité de rendu entre langages n’est pas un objectif — voir §1.

C — Écrire notre propre générateur pour C, C++ et Swift

Un extracteur possédé lisant les en-têtes cbindgen, rendant en Markdown.

Rejetée : tenable seulement pour des bindings générés. Un parseur C++ réel est un métier ; on paierait le coût d’écriture pour un résultat inférieur à Doxygen, et il faudrait re-décider dès la première ligne de C++ écrite à la main.

D — Sources en HTML5 plutôt qu’en Markdown

Rejetée : 290 fichiers à convertir, contributeurs contraints d’écrire du HTML, diffs de revue illisibles — pour un résultat que le couple front-matter + templates atteint sans rien sacrifier.

Mise en œuvre (référence)

Par étapes, chacune vérifiable :

1. Recherche — implémenter l’interface sur l’index produit par Zola. C’est le prérequis à toute bascule : perdre la recherche serait une régression.
2. Conversion en masse des ADR — les 145, deux langues, avec traitement explicite des cas hors-format.
3. Migration du reste de docs/ — fondateurs, specs, guides, notes.
4. Bascule — Zola devient /guide/, mdBook et maquette-zola/ sont retirés.
5. Contrôle de conformité — vérifier que tout nouvel ADR porte les rubriques obligatoires, bloquant sur les nouveaux, toléré sur l’existant via une liste d’exceptions déclarée, à la manière de docs/COVERAGE-EXCEPTIONS.md.

Suite

• Sections obligatoires : arrêter la liste définitive et le sort des 18 ADR sans structure canonique. Unifier « Alternatives rejetées » / « écartées ».
• Habillage de rustdoc et de Doxygen : feuille de style accordée et lien de retour, pour que la bascule entre surfaces ne donne pas l’impression de changer de site.
• DocC : à instruire quand une surface Swift existera.