Aller au contenu

Refactorisation Documentation - 23 Octobre 2025

🎯 Objectif

Réorganisation complète de la documentation MkDocs pour améliorer la navigation, la maintenabilité et la scalabilité.

📊 Résultat

  • Fichiers markdown : 80 fichiers organisés
  • Dossiers : 34 dossiers structurés logiquement
  • Warnings MkDocs : Réduits de ~90 à 3 (liens externes acceptables)
  • Build time : 23.75 secondes
  • Build status : ✅ Succès

🔄 Changements Majeurs

Phase 1 : Nettoyage racine docs/

  • ✅ Supprimé 3 dossiers vides : docsguides/, docsinfrastructure/, docsservices/
  • ✅ BOT_PROTECTION_DEPLOYMENT.md → changelog/bot-protection-2025-10-23.md
  • ✅ SERVER_ENVIRONMENT.md → infrastructure/environment-setup.md

Phase 2 : Réorganisation services/

Création de 8 catégories claires : 

services/
├── collaboration/     (Nextcloud, Rocket.Chat, Jitsi)
├── ai/               (Ollama, WhisperX, XTTS, NeuTTS, Tika, Faster-Whisper)
├── documents/        (Paperless-ngx, Paperless AI)
├── websites/         (Cristina, WP Clemence, WP SolidarLink)
├── apps/             (Impro Manager, n8n)
├── infrastructure/   (Monitoring, Glances, Dozzle, Portainer, Dashy, DB)
├── automation/       (Docker Autostart)
└── rag/             (Préparé pour futurs services RAG)

Phase 3 : Réorganisation guides/

Structure logique en 6 sections : 

guides/
├── getting-started/   (Setup VPS initial)
├── deployment/        (Docker Autostart, Systemd)
├── services/
│   ├── wordpress/     (3 guides)
│   ├── ai/           (3 guides)
│   ├── rag/          (4 guides)
│   ├── cms/          (2 guides)
│   ├── automation/   (2 guides)
│   └── monitoring/   (2 guides)
├── infrastructure/    (4 guides)
├── operations/        (Backup, Cloudflare, Photos)
└── advanced/          (MCP, API Portal, DevOps, LLM)

Phase 4 : Réorganisation reference/

reference/
├── docker/     (commands.md, compose-patterns.md)
├── nginx/      (proxy-config.md, debugging.md, headers.md, ssl-config.md)
├── security/   (basic-auth.md, ssl-certbot.md)
└── services/   (Préparé pour configs réutilisables)

Phase 5 : Infrastructure/

infrastructure/
├── docker.md
├── nginx.md
├── security.md
└── environment-setup.md

Phase 6 : Navigation MkDocs

Navigation complètement réécrite : - Services Déployés (catégorisés par fonction) - Infrastructure (vue d'ensemble architecture) - Guides (procédures étape par étape) - Référence Technique (snippets et configs)

🔗 Corrections de Liens

Liens corrigés automatiquement

  • ✅ 200+ liens internes mis à jour
  • ✅ Chemins relatifs corrigés (../ → ../../ selon contexte)
  • ✅ Anciens noms de guides renommés
  • ✅ Services déplacés référencés correctement

Patterns de correction appliqués

# Services
services/nextcloud.md → services/collaboration/nextcloud.md
services/whisperx.md → services/ai/whisperx.md
services/monitoring.md → services/infrastructure/monitoring.md

# Guides
guides/deployment/deploiement-vps.md → guides/getting-started/vps-initial-setup.md
guides/applications/whisper-services.md → guides/services/ai/whisper-deployment.md
guides/ai-rag/* → guides/services/rag/*

# Reference
reference/docker/common-commands.md → reference/docker/commands.md
reference/nginx/configuration.md → reference/nginx/proxy-config.md
reference/security/basic-auth-setup.md → reference/security/basic-auth.md

⚠️ Warnings Acceptables (3 restants)

Ces warnings concernent des liens vers server-configs/ qui est un dossier hors documentation : 1. guides/operations/backup-restore.md → ../../server-configs/README.md 2. guides/operations/backup-restore.md → ../../server-configs/INVENTORY.md 3. services/automation/docker-autostart.md → ../../server-configs/INVENTORY.md

Ces liens sont légitimes car ils pointent vers des fichiers de configuration du serveur qui ne font pas partie de la documentation publique.

✅ Bénéfices

  1. Navigation intuitive : Hiérarchie claire et prévisible
  2. Scalabilité : Facile d'ajouter de nouveaux services/guides
  3. Pas de duplication : Un seul emplacement par type d'information
  4. Maintenance facilitée : Structure claire = moins d'erreurs
  5. Performance : Build rapide (23.75s pour 80 fichiers)
  6. SEO amélioré : Arborescence logique pour les moteurs de recherche

📝 Prochaines Étapes Recommandées

  1. Déployer sur le serveur : 

    mkdocs build
rsync -avz site/ root@srv759970.hstgr.cloud:/var/www/docs/

  2. Créer une section RAG : Le dossier services/rag/ est prêt pour accueillir les futures docs RAGFlow, VideoRAG, etc.

  3. Compléter reference/services/ : Ajouter des configs réutilisables pour Redis, PostgreSQL, MongoDB

  4. Ajouter guides/getting-started/ : Créer plus de guides pour débutants (Docker basics, security first steps)

🔍 Structure Finale

docs/
├── index.md (liens mis à jour)
├── SERVER_STATUS.md (généré)
├── SERVICES_STATUS.md (généré)
├── services/
│   ├── collaboration/
│   ├── ai/
│   ├── rag/
│   ├── documents/
│   ├── websites/
│   ├── apps/
│   ├── infrastructure/
│   └── automation/
├── infrastructure/
├── guides/
│   ├── getting-started/
│   ├── deployment/
│   ├── services/
│   ├── infrastructure/
│   ├── operations/
│   └── advanced/
├── reference/
│   ├── docker/
│   ├── nginx/
│   ├── security/
│   └── services/
├── impro-manager/
├── changelog/
├── analysis/
└── archives/

📅 Timeline

  • Début : 23 octobre 2025 - 22h00
  • Fin : 23 octobre 2025 - 22h40
  • Durée totale : ~40 minutes
  • Commits : Refactorisation complète en une session

Refactorisation effectuée automatiquement avec Claude Code