Convention de documentation Quantis

Cette page est la convention : une codification de documentation partagée par tous les modules Quantis, pour une navigation homogène d'un module à l'autre et une exploitation à l'échelle de la plateforme. ActuaryLab en est l'implémentation de référence (modèle doc-as-service) ; les modules suivants la copient.

Les quatre piliers

1. Taxonomie — Diátaxis

Toute doc se range dans quatre catégories (jamais d'autres) :

Catégorie	Question	Dossier
Tutoriels	« Comment j'apprends en faisant ? »	docs/tutorials/
Guides pratiques	« Comment je résous cette tâche ? »	docs/how-to/
Référence	« Quel est le détail factuel ? »	docs/specs/, docs/reference/
Explication	« Pourquoi c'est ainsi ? »	docs/explanation/, docs/plan/, docs/formalisation/

Plus une rubrique À propos (docs/about/) pour la méta (cette page, provenance).

2. Outil — MkDocs Material + charte BFEV

• mkdocs.yml à la racine du dépôt, thème Material, langue fr.
• Charte commune : docs/assets/extra.css (palette vert #237227 / ambre #ffaa00), Roboto. La palette est identique pour tous les modules — seuls site_name et logo changent (unité visuelle Quantis).
• arithmatex + MathJax pour les formules (utile aux modules à contenu mathématique).

3. Déploiement — doc-as-service

La doc est un service du stack Compose du module (docs/Dockerfile → nginx), géré au même titre que backend / frontend, pas un déploiement séparé.

Leçon de bfev (module 1)

Le module bfev déploie sa doc séparément — considéré rétrospectivement comme une erreur. ActuaryLab corrige le tir : doc = service du module. À répliquer partout, et à rétrofiter sur bfev.

Domaine : docs.<module>.nedcore.net (ici docs.quantis-actuarylab.nedcore.net), aux côtés de app. et api..

4. Cycle de vie

La doc suit le versionnage du code : même dépôt, même cycle de release. Travail terminé → maj docs/ → commit + push → Dokploy redéploie → page à jour. Multi-versions via mike si/quand le besoin apparaît.

Adopter la convention dans un nouveau module

1. Copier mkdocs.yml, docs/assets/, docs/Dockerfile, docs/nginx.conf, requirements-docs.txt ; ajuster site_name et le logo.
2. Ajouter le service docs au docker-compose.yml du module.
3. Ranger le contenu dans les quatre dossiers Diátaxis.
4. Ajouter le domaine docs.<module>.nedcore.net dans Dokploy.

Dette connue (à durcir)

• Build en mkdocs build non-strict : les specs importées portent des liens relatifs hérités. Passer à --strict une fois les liens nettoyés.
• Mutualisation : la machinerie est aujourd'hui copiée par module. Quand un 3ᵉ module arrive, extraire un outil partagé quantis-docs (le coût DRY justifiera alors le refactor — durcissement juste-à-temps).