Passer au contenu principal

Outils de documentation

La documentation est construite à l'aide de Docusaurus et se trouve dans le dossier documentation. La documentation est hébergée sur GitHub Pages et n'est plus incluse dans l'image du conteneur Docker.

Structure des dossiers​

documentation/
├── docs/              # Documentation markdown files (English source)
│   ├── api-reference/
│   ├── development/
│   ├── installation/
│   ├── migration/
│   ├── release-notes/
│   └── user-guide/
├── i18n/              # Translations (auto-generated by translation workflow)
│   ├── de/            # German
│   ├── es/            # Spanish
│   ├── fr/            # French
│   ├── hi/            # Hindi
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   ├── landing/       # Homepage HTML + CSS (English source; locale copies in landing/i18n/)
│   ├── pages/         # Additional pages (homepage shell, 404)
│   └── theme/         # Swizzled theme (navbar)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
└── package.json       # Dependencies and scripts

Internationalisation (i18n)​

La documentation utilise le système i18n intégré de Docusaurus avec l'anglais comme locale par défaut. Le contenu traduit se trouve dans i18n/{locale}/docusaurus-plugin-content-docs/current/, reflétant la structure du dossier docs/.

  • Fichiers source : docs/**/*.md (anglais)
  • Fichiers traduits : i18n/{locale}/docusaurus-plugin-content-docs/current/**/*.md
  • Traductions de l'interface utilisateur : i18n/{locale}/docusaurus-theme-classic/*.json et autres fichiers JSON
  • Captures d'écran localisées : i18n/{locale}/docusaurus-plugin-content-docs/current/**/assets, générées par pnpm take-screenhots dans le répertoire de base.

La commande pnpm write-translations extrait les chaînes de l'interface utilisateur (du thème Docusaurus et des composants personnalisés) dans des fichiers de traduction JSON. Le script pnpm translate (depuis documentation/, déléguant à la racine du dépôt) exécute ai-i18n-tools pour traduire le Markdown, le JSON, les SVG et le code HTML de la page de destination selon ai-i18n-tools.config.json.

La page d'accueil de la documentation est src/landing/landing.html encapsulé par src/pages/index.tsx. Modifiez le fichier HTML pour le contenu textuel ; les copies localisées se trouvent sous src/landing/i18n/ et sont générées par pnpm i18n:translate:docs.

important

Modifiez uniquement les fichiers situés dans docs/, la source de la page de destination src/landing/landing.html et les fichiers JSON sources dans i18n/en-GB/. Les fichiers Markdown traduits sous i18n/{other-locales}/ et les copies de la page de destination sous src/landing/i18n/ sont générés et ne doivent pas être modifiés manuellement.

Locales prises en charge​

LocaleLangueRépertoire
en-GBAnglais (par défaut)docs/ (source)
deAllemandi18n/de/docusaurus-plugin-content-docs/current/
esEspagnoli18n/es/docusaurus-plugin-content-docs/current/
frFrançaisi18n/fr/docusaurus-plugin-content-docs/current/
hiHindii18n/hi/docusaurus-plugin-content-docs/current/
pt-BRPortugais brésilieni18n/pt-BR/docusaurus-plugin-content-docs/current/
zh-HansChinois simplifiéi18n/zh-Hans/docusaurus-plugin-content-docs/current/

Traduire la documentation​

La documentation utilise un système de traduction alimenté par l'IA pour traduire à la fois le contenu (fichiers markdown) et les chaînes de l'interface utilisateur (de Docusaurus et des composants personnalisés). Le contenu source est en anglais (docs/), et les traductions sont générées pour l'allemand, le français, l'espagnol, le portugais brésilien, l'hindi et le chinois simplifié.

Fonctionnement de la traduction​

  1. Chaînes de l'interface utilisateur Docusaurus : pnpm write-translations extrait les chaînes du thème/personnalisées dans i18n/en/*.json.
  2. Traduction par IA (OpenRouter ; configuration dans ai-i18n-tools.config.json à la racine du dépôt) : à partir de documentation/, pnpm translate exécute le script racine i18n:translate (chaînes de l'interface utilisateur, SVG, markdown/JSON Docusaurus et modèles de notification par défaut) dans documentation/i18n/, src/locales/ et src/locales/templates/ selon la configuration.
  3. Construction : pnpm build génère du HTML statique pour toutes les locales sous documentation/build/.

Exécution de la traduction​

cd documentation
pnpm translate          # Same as repo root: i18n:translate (ui + svg + docs + json)
pnpm translate:docs
pnpm translate:json
pnpm translate:svg
pnpm translate:ui
pnpm translate:status

Les drapeaux CLI sont définis par ai-i18n-tools ; exécutez pnpm exec ai-i18n-tools --help à partir de la racine du dépôt ou consultez Translation Workflow.

Remplacements de traduction manuels​

Modifiez documentation/glossary-user.csv (et effacez éventuellement les entrées obsolètes sous .translation-cache/ à la racine du dépôt), puis réexécutez la commande pnpm translate:* pertinente.

Commandes courantes​

Tout les commandes doivent être exécutées à partir du répertoire documentation :

Développement​

Démarrez le serveur de développement avec rechargement à chaud pour une locale spécifique :

cd documentation
pnpm start:en    # English (default)
pnpm start:fr    # French
pnpm start:de    # German
pnpm start:es    # Spanish
pnpm start:pt-br # Brazilian Portuguese

Le site sera disponible à http://localhost:3000/duplistatus/ (ou au port disponible suivant). Le chemin /duplistatus/ correspond à GitHub Pages baseUrl et le bouton Aide dans l'application établit des liens.

Build​

Générez le site de documentation pour la production :

cd documentation
pnpm build

Cela génère des fichiers HTML statiques dans le répertoire documentation/build.

Servir la build de production​

Prévisualisez la build de production localement :

cd documentation
pnpm serve

Cela sert le site généré à partir du répertoire documentation/build.

Autres commandes utiles​

  • pnpm clear - Effacer le cache Docusaurus
  • pnpm typecheck - Exécuter la vérification des types TypeScript
  • pnpm write-heading-ids - Écrire des ancres de titre {/* #id */} explicites dans le markdown en utilisant la syntaxe de commentaire MDX Docusaurus (exécutez à partir de documentation/ pour des liens stables entre les traductions). L'interface de ligne de commande ignore les titres h1, que Docusaurus utilise comme étiquettes de barre latérale.

Génération de README.md​

Le fichier README.md du projet est généré automatiquement à partir de documentation/docs/intro.md pour maintenir la synchronisation du README du dépôt GitHub avec la documentation Docusaurus.

Pour générer ou mettre à jour le fichier README.md :

./scripts/generate-readme-from-intro.sh

Ce script :

  • Extrait la version actuelle de package.json et ajoute un badge de version
  • Copie le contenu de documentation/docs/intro.md
  • Convertit les admonitions Docusaurus (note, tip, warning, etc.) en alertes de style GitHub
  • Convertit tous les liens Docusaurus relatifs en URLs absolues de documentation GitHub (https://wsj-br.github.io/duplistatus/...)
  • Convertit les chemins d'images de /img/ à documentation/static/img/ pour la compatibilité GitHub
  • Supprime le bloc IMPORTANT de migration et ajoute une section Informations de migration avec un lien vers la documentation Docusaurus
  • Génère une table des matières en utilisant doctoc
  • Génère README_dockerhub.md avec un formatage compatible Docker Hub (convertit les images et les liens en URLs absolues, convertit les alertes GitHub en format basé sur les emojis)
  • Génère les notes de version GitHub (RELEASE_NOTES_github_VERSION.md) à partir de documentation/docs/release-notes/VERSION.md (convertit les liens et les images en URLs absolues)

Mettre à jour le README pour Docker Hub​

Le script generate-readme-from-intro.sh génère automatiquement README_dockerhub.md avec un formatage compatible Docker Hub. Il :

  • Copie README.md vers README_dockerhub.md
  • Convertit les chemins d'images relatifs en URLs brutes GitHub absolues
  • Convertit les liens de documents relatifs en URLs blob GitHub absolues
  • Convertit les alertes de style GitHub ([!NOTE], [!WARNING], etc.) en format basé sur les emojis pour une meilleure compatibilité Docker Hub
  • S'assure que toutes les images et tous les liens fonctionnent correctement sur Docker Hub

Générer les notes de version GitHub​

Le script generate-readme-from-intro.sh génère automatiquement les notes de version GitHub lors de son exécution. Il :

  • Lit les notes de version de documentation/docs/release-notes/VERSION.md (où VERSION est extrait de package.json)
  • Change le titre de « # Version xxxx » à « # Notes de version - Version xxxxx »
  • Convertit les liens markdown relatifs en URLs absolues de documentation GitHub (https://wsj-br.github.io/duplistatus/...)
  • Convertit les chemins d'images en URLs brutes GitHub (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...) pour un affichage correct dans les descriptions de version
  • Gère les chemins relatifs avec le préfixe ../
  • Préserve les URLs absolues (http:// et https://) inchangées
  • Crée RELEASE_NOTES_github_VERSION.md à la racine du projet

Exemple :

# This will generate both README.md and RELEASE_NOTES_github_VERSION.md
./scripts/generate-readme-from-intro.sh

Le fichier de notes de version généré peut être copié et collé directement dans la description de la version GitHub. Tous les liens et les images fonctionneront correctement dans le contexte de la version GitHub.

Prendre des captures d'écran pour la documentation​

pnpm take-screenshots

Ou exécutez directement : pnpm take-screenshots (utilisez --env-file=.env si nécessaire pour les variables d'environnement).

Ce script prend automatiquement des captures d'écran de l'application à des fins de documentation. Il :

  • Après les vérifications env et health, exécute pnpm exec playwright install pour que les navigateurs Playwright soient présents
  • Lance un navigateur headless (Playwright Chromium)
  • Se connecte en tant qu'administrateur et utilisateur régulier
  • Navigue à travers diverses pages (tableau de bord, détails du serveur, paramètres, etc.)
  • Prend des captures d'écran à différentes tailles de viewport
  • Enregistre les captures d'écran dans documentation/static/assets/ (anglais) ou documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets (autres locales)

Prérequis :

  • Le serveur de développement doit être en cours d'exécution sur http://localhost:8666
  • Les variables d'environnement doivent être définies, ajoutez-les à votre fichier .env ou exportez-les :
    • ADMIN_PASSWORD : Mot de passe pour le compte Admin
    • USER_PASSWORD : Mot de passe pour le compte utilisateur ordinaire

Options : --locale limite les captures d'écran à une ou plusieurs locales (séparées par des virgules). Si omis, toutes les locales sont capturées. Locales valides : en-GB, de, fr, es, pt-BR, hi, zh-Hans. Utilisez -h ou --help pour afficher l'utilisation.

Exemple :

export ADMIN_PASSWORD="your-admin-password"
export USER_PASSWORD="your-user-password"
pnpm take-screenshots
# All locales (default):
pnpm take-screenshots
# Single locale:
pnpm take-screenshots --locale en-GB
# Multiple locales:
pnpm take-screenshots --locale en-GB,de,pt-BR

Déployer la documentation​

Pour déployer la documentation sur GitHub Pages, vous devez générer un jeton d'accès personnel GitHub. Allez à GitHub Personal Access Tokens et créez un nouveau jeton avec la portée repo.

Quand vous avez le jeton, stockez-le dans le magasin d'identifiants Git (par exemple en utilisant git config credential.helper store ou le gestionnaire d'identifiants de votre système).

Ensuite, pour déployer la documentation sur GitHub Pages, exécutez la commande suivante à partir du répertoire documentation :

pnpm run deploy

Cela créera la documentation et la poussera vers la branche gh-pages du dépôt, et la documentation sera disponible à https://wsj-br.github.io/duplistatus/.

Utilisation de la documentation​

Pour le flux de travail de traduction complet (gestion du glossaire, traduction par IA, gestion du cache), consultez Translation Workflow.

Fichiers source​

  • Contenu de la documentation : fichiers markdown en anglais dans documentation/docs/
  • Traductions de l'interface utilisateur : fichiers JSON en anglais dans documentation/i18n/en/ (générés automatiquement par pnpm write-translations)
  • Navigation de la barre latérale : documentation/sidebars.ts
  • Configuration de Docusaurus : documentation/docusaurus.config.ts
  • Composants React personnalisés : documentation/src/components/
  • Ressources statiques : documentation/static/
  • Page d'accueil principale : documentation/docs/intro.md (source pour générer README.md)

Ajouter de nouveaux composants​

  1. Créez votre composant React dans documentation/src/components/
  2. Exportez-le depuis documentation/src/theme/MDXComponents.js pour le rendre disponible dans MDX
  3. Si le composant inclut des chaînes d'interface utilisateur traduisibles, exécutez pnpm write-translations pour les extraire
  4. Exécutez pnpm translate pour traduire les nouvelles chaînes dans toutes les locales

Ajouter de nouvelles pages de documentation​

  1. Créez un nouveau fichier .md dans documentation/docs/ (ou un sous-répertoire)
  2. Ajoutez-le à la barre latérale dans documentation/sidebars.ts
  3. Exécutez pnpm write-translations pour mettre à jour la structure des fichiers de traduction
  4. Exécutez pnpm write-heading-ids pour générer les ID de titre (ancres)
  5. Exécutez pnpm translate pour traduire la nouvelle page dans toutes les locales
  6. Créez et testez : pnpm build

Ressources statiques​

  • Images : placez-les dans documentation/static/img/ et référencez-les avec /img/filename.png dans le markdown
  • Téléchargements/PDF : placez-les dans documentation/static/ et référencez-les avec /filename.pdf
  • Ressources par locale : si une ressource doit être spécifique à une locale (par exemple, des captures d'écran), placez-la dans documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets/

Créer et tester​

cd documentation
pnpm build            # Builds all locales
pnpm serve            # Preview the built site locally
pnpm start:en         # Development server for English
pnpm start:pt-br      # Development server for Portuguese

Testez toujours vos modifications au moins dans la locale anglaise par défaut et dans une autre locale pour vous assurer que les traductions s'affichent correctement.