Aller au contenu

Lancement du site bilingue

Ticket #84 + #85 : Récupération, Restructuration et Déploiement de la Documentation Technique
Type : Recovery / Refactoring / Infrastructure
Composants Affectés : Structure du Projet, mkdocs.yml, GitHub Actions, Nginx Config

1. Contexte et Objectif Stratégique

L'objectif des travaux documentés dans le présent rapport était de passer d'une documentation unilingue à une documentation bilingue (EN/FR) sur docs.invest.justingoufo.com. Historique de la situation : Une première tentative d'implémentation du bilinguisme et de personnalisation du footer, confiée à l'Agent IA (Gemini) dans Firebase Studio, a été marqué d'hallucinations techniques sévères, au point de briser la structure du site, le rendant inopérant (Erreur 403). Changement d'approche : Ce rapport documente la reprise en main du projet via une stratégie d'investigation dirigée sur Google AI Studio pour auditer les dégâts, assainir l'architecture, garantir un déploiement fiable, et restaurer le site.

2. Processus d'Investigation et de Refactoring

  1. Audit de l'État Post-Incident :

    • Constat : L'architecture du projet était fragmentée (fichiers sources enfouis dans project_docs), rendant la maintenance complexe.
    • Blocage i18n : La structure des dossiers (noms différents en FR et EN) était incompatible avec le plugin de traduction, une séquelle probable de la tentative précédente.

  2. Refactoring du Système de Fichiers (Standardisation) :

    • Action : Suppression de la couche superflue project_docs pour remonter la configuration à la racine.
    • Action : Normalisation "Miroir" des noms de fichiers. Les fichiers français ont été renommés pour correspondre exactement aux noms anglais (ex: adoption de activity_report pour les deux langues), condition sine qua non pour le fonctionnement du plugin.

  3. Correction de la Configuration MkDocs :

    • Action : Abandon de la traduction automatique implicite au profit d'une surcharge explicite (override) du menu dans le fichier de configuration. Cela a permis de restaurer les titres et la navigation en français qui avaient été perdus.

  4. Débogage du Pipeline CI/CD (GitHub Actions) :

    • Erreur : Le pipeline échouait suite aux déplacements de fichiers.
    • Correction : Mise à jour des chemins dans le workflow (deploy-docs.yml) et ajout explicite au dépôt des fichiers de dépendances (docs-requirements.txt) qui avaient été omis.

  5. Résolution de l'incident de Déploiement (Erreur 404 Nginx) :

    • Symptôme : Site inaccessible malgré un build réussi.
    • Cause : Désynchronisation entre le dossier cible défini dans les Secrets GitHub et la configuration du serveur Nginx.
    • Correction : Création de l'arborescence physique sur le VPS et alignement du Secret DOCS_TARGET_DIR.

3. Cause Racine Identifiée (Synthèse)

L'instabilité du projet résultait d'une dette technique introduite par une automatisation peu supervisée : structure de fichiers incohérente, configuration i18n erronée et déconnexion entre le code source et l'infrastructure de déploiement.

4. Solution Implantée

  • Architecture Assainie : Structure bilingue propre (docs/ et docs/fr/) avec correspondance stricte des fichiers.
  • Contrôle Repris : Configuration manuelle et explicite du mkdocs.yml pour garantir la stabilité.
  • Infrastructure : Pipeline CI/CD et serveur Nginx parfaitement synchronisés.

5. Justification et Bénéfices

  • Rétablissement du Service : La documentation est de nouveau en ligne et fonctionnelle.
  • Fiabilité : Le projet est sorti de l'état instable laissé par l'agent IA. L'architecture actuelle est standardisée, facilitant les futures mises à jour par l'humain.
  • Expérience Utilisateur : Le basculement de langue et la navigation sont désormais fluides et sans erreur.