ADR-010 — Publication de la doc (MkDocs, Cloudflare Pages, accès privé)

Statut : proposee

Contexte

La doc est en Markdown dans Git. L'associé, non technique, doit la consulter et suivre son évolution ; elle contient des prix, des devis et le contrat revendeur, donc elle ne doit pas être publique. Elle servira ensuite de base au code (NFR-007).

Options considérées

  1. MkDocs sur Cloudflare Pages, protégé par Cloudflare Access, dépôt GitHub privé.
  2. Wiki ou outil de notes en ligne (Notion…) : la doc quitterait Git.
  3. Site public.

Décision

Option 1, avec le thème MkDocs readthedocs (intégré, sans dépendance supplémentaire).

Raisons

  • Git reste la source de vérité ; le site n'est qu'une vue de lecture.
  • Cloudflare Access (code par email) évite de gérer des mots de passe ; il protège aussi les URL de prévisualisation par branche.
  • Un build strict (check_docs.py puis mkdocs build --strict) empêche de publier une doc incohérente.
  • Mermaid est versionné dans docs/assets/js/ : pas de CDN tiers, build reproductible.

Conséquences

Positives : relecture par l'associé sur une URL de prévisualisation avant fusion ; doc et code versionnés ensemble. Négatives / compromis acceptés : l'associé lit mais ne modifie pas la doc (pas d'outil d'édition ni de commentaires au départ) ; thème moins riche que Material (pas d'onglets ni de mode sombre). À surveiller : MkDocs 2.0 n'est pas compatible, versions épinglées dans requirements.txt ; réévaluer l'édition ou les commentaires par l'associé après quelques CR.

Réversibilité

Faible coût : le contenu est du Markdown portable ; seuls mkdocs.yml, le hook hooks/ids.py et les .nav.yml sont propres à MkDocs.

Liens

NFR-007, docs/07-ingenierie/workflow-dev.md.