Documentation Consultable - Proposition

Ce document propose une solution pour mettre en place une documentation consultable via un site web dédié.

🎯 Objectifs

1. Accessibilité : Documentation accessible via un site web dédié
2. Recherche : Recherche full-text dans toute la documentation
3. Navigation : Navigation intuitive avec table des matières
4. Mise à jour : Synchronisation automatique avec les fichiers Markdown
5. Versioning : Support de plusieurs versions de la documentation
6. Thème : Interface moderne et responsive

📋 Solutions Proposées

Option 1 : Docusaurus (Recommandé) ⭐

Avantages :

• ✅ Créé par Meta (Facebook), très populaire et maintenu
• ✅ Excellent support Markdown avec MDX
• ✅ Recherche intégrée (Algolia DocSearch ou local)
• ✅ Thème moderne et personnalisable
• ✅ Support multi-langues
• ✅ Versioning intégré
• ✅ Blog intégré (optionnel)
• ✅ SEO optimisé
• ✅ Facile à déployer (Vercel, Netlify, GitHub Pages)

Inconvénients :

• ⚠️ Nécessite Node.js pour le build
• ⚠️ Configuration initiale plus complexe que MkDocs

Structure proposée :

docs-site/
├── docusaurus.config.js
├── sidebars.js
├── package.json
├── src/
│   ├── css/
│   │   └── custom.css
│   └── pages/
│       └── index.tsx
└── docs/
    ├── getting-started/
    ├── architecture/
    ├── backend/
    ├── frontend/
    ├── guides/
    └── api/

Exemple de configuration :

// docusaurus.config.js
module.exports = {
  title: "Aaperture CRM Documentation",
  tagline: "CRM pour photographes",
  url: "https://docs.aaperture.dev",
  baseUrl: "/",
  onBrokenLinks: "throw",
  onBrokenMarkdownLinks: "warn",
  favicon: "img/favicon.ico",
  organizationName: "aaperture",
  projectName: "aaperture-docs",
  themeConfig: {
    navbar: {
      title: "Aaperture",
      logo: {
        alt: "Aaperture Logo",
        src: "img/logo.svg",
      },
      items: [
        {
          type: "doc",
          docId: "getting-started/intro",
          position: "left",
          label: "Documentation",
        },
        {
          type: "doc",
          docId: "api/overview",
          position: "left",
          label: "API",
        },
        {
          href: "https://github.com/aaperture/aaperture",
          label: "GitHub",
          position: "right",
        },
      ],
    },
    footer: {
      style: "dark",
      links: [
        {
          title: "Docs",
          items: [
            {
              label: "Getting Started",
              to: "/docs/getting-started/intro",
            },
            {
              label: "Architecture",
              to: "/docs/architecture/overview",
            },
          ],
        },
        {
          title: "Community",
          items: [
            {
              label: "GitHub",
              href: "https://github.com/aaperture/aaperture",
            },
          ],
        },
      ],
    },
    algolia: {
      appId: "YOUR_APP_ID",
      apiKey: "YOUR_SEARCH_API_KEY",
      indexName: "aaperture-docs",
    },
  },
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          sidebarPath: require.resolve("./sidebars.js"),
          editUrl: "https://github.com/aaperture/aaperture/edit/main/docs/",
        },
        theme: {
          customCss: require.resolve("./src/css/custom.css"),
        },
      },
    ],
  ],
};

Déploiement :

• Vercel : Connexion GitHub → Auto-deploy sur push
• Netlify : Connexion GitHub → Auto-deploy sur push
• GitHub Pages : Action GitHub pour build et deploy

Option 2 : MkDocs

Avantages :

• ✅ Simple et léger (Python)
• ✅ Configuration YAML simple
• ✅ Thèmes disponibles (Material Theme très populaire)
• ✅ Recherche intégrée
• ✅ Support Markdown natif
• ✅ Facile à déployer

Inconvénients :

• ⚠️ Moins de fonctionnalités que Docusaurus
• ⚠️ Versioning moins avancé
• ⚠️ Nécessite Python

Structure proposée :

docs-site/
├── mkdocs.yml
├── requirements.txt
└── docs/
    ├── index.md
    ├── getting-started/
    ├── architecture/
    ├── backend/
    ├── frontend/
    └── guides/

Exemple de configuration :

# mkdocs.yml
site_name: Aaperture CRM Documentation
site_description: Documentation complète du CRM pour photographes
site_url: https://docs.aaperture.dev

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: dark
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight

nav:
  - Home: index.md
  - Getting Started:
      - getting-started/intro.md
      - getting-started/installation.md
  - Architecture:
      - architecture/overview.md
      - architecture/data-flow.md
  - Backend:
      - backend/overview.md
      - backend/modules.md
  - Frontend:
      - frontend/overview.md
      - frontend/components.md
  - Guides:
      - guides/calendar-sync.md
      - guides/booking-system.md
  - API:
      - api/overview.md
      - api/authentication.md

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details
  - tables
  - attr_list
  - md_in_html

plugins:
  - search
  - minify:
      minify_html: true

Option 3 : VuePress

Avantages :

• ✅ Basé sur Vue.js
• ✅ Thème par défaut élégant
• ✅ Support Markdown avec composants Vue
• ✅ Recherche intégrée
• ✅ Facile à personnaliser

Inconvénients :

• ⚠️ Moins populaire que Docusaurus
• ⚠️ Nécessite Node.js

🚀 Recommandation : Docusaurus

Pourquoi Docusaurus :

1. Popularité : Utilisé par de nombreux projets open-source majeurs
2. Fonctionnalités : Versioning, recherche, blog, i18n intégrés
3. Écosystème : Nombreux plugins et thèmes disponibles
4. Maintenance : Projet actif avec support communautaire fort
5. Déploiement : Intégration facile avec Vercel/Netlify

📁 Structure de Documentation Proposée

docs/
├── getting-started/
│   ├── intro.md
│   ├── installation.md
│   └── quick-start.md
├── architecture/
│   ├── overview.md
│   ├── data-flow.md
│   └── scopes/
│       ├── sessions.md
│       ├── contacts.md
│       ├── quotes-invoices.md
│       └── calendar.md
├── backend/
│   ├── overview.md
│   ├── modules.md
│   ├── database.md
│   └── api/
│       ├── authentication.md
│       ├── sessions.md
│       └── contacts.md
├── frontend/
│   ├── overview.md
│   ├── components.md
│   ├── routing.md
│   └── state-management.md
├── guides/
│   ├── calendar-sync.md
│   ├── booking-system.md
│   ├── ai-search.md
│   └── workflows.md
├── api/
│   ├── overview.md
│   ├── authentication.md
│   └── endpoints.md
└── reference/
    ├── environment-variables.md
    ├── timeout-management.md
    └── migration-process.md

🔧 Mise en Place

Étape 1 : Initialisation

# Créer le répertoire de documentation
mkdir docs-site
cd docs-site

# Initialiser Docusaurus
npx create-docusaurus@latest . classic

# Ou avec npm
npm create docusaurus@latest . classic

Étape 2 : Configuration

1. Copier les fichiers Markdown existants dans docs/
2. Configurer docusaurus.config.js
3. Configurer sidebars.js pour la navigation
4. Personnaliser le thème dans src/css/custom.css

Étape 3 : Scripts de Synchronisation

Créer un script pour synchroniser automatiquement les fichiers depuis docs/ :

#!/bin/bash
# sync-docs.sh

# Copier les fichiers de documentation
cp -r ../docs/* ./docs/

# Exclure certains fichiers
rm -f ./docs/README.md
rm -f ./docs/AGENTS*.md  # Garder dans repo, pas dans site public

echo "Documentation synchronisée"

Étape 4 : Déploiement

Option A : Vercel (Recommandé)

1. Créer un compte Vercel
2. Connecter le repository GitHub
3. Configurer le build :
   • Build Command: npm run build
   • Output Directory: build
4. Déployer automatiquement sur chaque push

Option B : Netlify

1. Créer un compte Netlify
2. Connecter le repository GitHub
3. Configurer le build :
   • Build command: npm run build
   • Publish directory: build
4. Déployer automatiquement sur chaque push

Option C : GitHub Pages

1. Créer une GitHub Action pour build et deploy
2. Configurer GitHub Pages dans les settings du repo
3. Déployer automatiquement sur chaque push

📝 Migration des Fichiers Existants

Les fichiers existants dans docs/ peuvent être organisés ainsi :

• ARCHITECTURE.md → architecture/overview.md
• BACKEND.md → backend/overview.md
• FRONTEND.md → frontend/overview.md
• ROADMAP.md → guides/roadmap.md
• architecture/scopes.md → architecture/scopes.md
• CALENDAR_SYNC_ARCHITECTURE.md → guides/calendar-sync.md
• BOOKING_SYSTEM.md → guides/booking-system.md
• AI_SEARCH_ARCHITECTURE.md → guides/ai-search.md
• TIMEOUT_MANAGEMENT.md → reference/timeout-management.md
• MIGRATION_PROCESS.md → reference/migration-process.md
• DISASTER_RECOVERY.md → reference/disaster-recovery.md

🔍 Recherche

Option 1 : Algolia DocSearch (Gratuit pour projets open-source)

1. S'inscrire sur Algolia DocSearch
2. Soumettre le site pour indexation
3. Configurer les clés dans docusaurus.config.js

Option 2 : Recherche Locale

Docusaurus inclut une recherche locale par défaut (moins performante mais fonctionnelle).

🎨 Personnalisation

Logo et Favicon

Placer les fichiers dans static/img/ :

• logo.svg - Logo de la navbar
• favicon.ico - Favicon

Couleurs

Personnaliser dans docusaurus.config.js :

themeConfig: {
  colorMode: {
    defaultMode: 'light',
    disableSwitch: false,
    respectPrefersColorScheme: true,
  },
  // ...
}

CSS Personnalisé

Modifier src/css/custom.css pour personnaliser les styles.

📊 Métriques et Analytics

Intégrer Google Analytics ou Plausible Analytics :

// docusaurus.config.js
themeConfig: {
  googleAnalytics: {
    trackingID: 'G-XXXXXXXXXX',
    anonymizeIP: true,
  },
  // Ou
  gtag: {
    trackingID: 'G-XXXXXXXXXX',
    anonymizeIP: true,
  },
}

✅ Checklist de Mise en Place

• Initialiser Docusaurus
• Configurer docusaurus.config.js
• Configurer sidebars.js
• Migrer les fichiers Markdown existants
• Organiser la structure de documentation
• Personnaliser le thème (logo, couleurs)
• Configurer la recherche (Algolia ou locale)
• Tester le build local
• Configurer le déploiement (Vercel/Netlify)
• Configurer le domaine personnalisé (optionnel)
• Ajouter les métriques (Google Analytics)
• Documenter le processus de mise à jour

🔗 Ressources

• Docusaurus Documentation
• Docusaurus Tutorial
• MkDocs Documentation
• VuePress Documentation

📝 Notes

• La documentation peut rester dans le repository principal (docs/) et être synchronisée vers le site
• Les fichiers sensibles (AGENTS*.md) peuvent être exclus du site public
• Le site peut être mis à jour automatiquement via CI/CD sur chaque push
• Un domaine personnalisé peut être configuré (ex: docs.aaperture.dev)