Aller au contenu

Contribuer à la doc

Cette doc MkDocs Material agrège du contenu éparpillé dans le repo : les projets api, front-mobile-app et front-app peuvent maintenir leur propre documentation à côté de leur code, et tout est rassemblé ici pour une lecture unifiée.

Structure

  • Général — documentation transverse : Bricks Intel, Doppler, navigation IDE, migrations historiques, flux SPV
  • Architecture overview — cartographie technique : apps, API, auth, infra, intégrations externes
  • Postmortems — analyses post-incident
  • API — backend NestJS : vue d'ensemble, modules, endpoints/contrôleurs
  • Mobile — app React Native investisseur : vue d'ensemble, tracking, flows
  • Web — apps web (front-app, etc.)

Éditer une page

Chaque fichier .md de cette doc est versionné dans le monorepo. Pour modifier une page, édite son fichier source directement dans le repo (l'icône GitHub en haut à droite ouvre le dépôt).

Documenter du code

Crée un fichier .md à côté du code dans l'un des trois projets synchronisés — api (→ API), front-mobile-app (→ Mobile), front-app (→ Web) — par exemple projects/api/src/auth/docs/auth.md. Il sera détecté automatiquement et apparaîtra dans la nav. Aucune config à modifier. Les autres projets (bricksoffice-projects, bricksoffice-invest, app-pdp-financement, common, storybook, storybook-native) ne sont pas scannés pour ces .md ; seules leurs règles/skills/commandes d'agents y sont remontées.

Pour customiser un titre, l'ordre, ou cacher une page, ajoute un fichier .pages (YAML) dans le dossier concerné. Voir la doc du plugin awesome-pages.

Composants visuels

De quoi rendre une page lisible et jolie — tout est déjà activé. Exemples vivants : la vue d'ensemble Primary Purchase et les Tests d'intégration.

Tags — chips en tête de page, via le front-matter :

---
tags:
  - api
  - tests
---

Admonitions — encadrés colorés (note, tip, warning, info, example, abstract). Préfixe ??? au lieu de !!! pour un bloc repliable :

!!! tip "Astuce"
    Contenu indenté de 4 espaces.

Onglets de contenu — pour présenter des variantes côte à côte (corps indenté de 4 espaces) :

=== "Option A"
    Contenu A
=== "Option B"
    Contenu B

Diagrammes Mermaid — bloc ```mermaid. Pour rester cohérent d'une page à l'autre, réutilise la palette classDef partagée (suffixe une node avec :::action, etc.) :

classDef endpoint fill:#4f46e5,color:#fff,stroke:#3730a3   %% point d'entrée (route)
classDef action   fill:#0ea5e9,color:#fff,stroke:#0369a1   %% étape / traitement
classDef status   fill:#fef3c7,color:#78350f,stroke:#d97706 %% état / attente
classDef success  fill:#10b981,color:#fff,stroke:#047857   %% succès
classDef failure  fill:#ef4444,color:#fff,stroke:#b91c1c   %% échec
classDef neutral  fill:#6b7280,color:#fff,stroke:#374151   %% neutre / terminal

Liens vers le code — via les macros, jamais d'URL en dur (la branche develop est gérée pour toi) :

[`fichier.ts`]({{ github_blob }}/projects/api/src/…/fichier.ts)
[`dossier/`]({{ github_tree }}/projects/api/src/…)

Code — bouton copie automatique, annotations # (1)!, et surlignage de lignes (hl_lines).

Build strict

strict: true : un lien cassé fait échouer le build. Le plugin macros interprète la syntaxe à doubles accolades partout (même dans les blocs de code) — pour en afficher une littéralement, enveloppe-la dans une chaîne Jinja : {{ "{{ … }}" }}.

Pour le système de build, la nav et le déploiement : voir Système de documentation.

Lancer la doc en local

pnpm dev:docs
# → http://localhost:8000

Le hot reload est actif : sauvegarder, créer ou supprimer un .md (ou une rule/skill .cursor/) rafraîchit le navigateur en moins de ~10 s, rebuild MkDocs compris.