angular-template documentation

📘 DOCUMENTATION 📘



SOMMAIRE

COMPODOC COMPODOC

INTRODUCTION

Compodoc est un outil de génération de documentation pour les applications Angular. Compodoc est le moteur utilisé pour analyser le code TypeScript (Modules, Components, Injectables, Routes, Interfaces...) et générer un site web statique complet avec des graphiques de dépendances et une navigation fluide.

🔗 Compodoc Documentation

Dans ce projet, nous avons poussé l'intégration plus loin pour permettre une double navigation fluide :

  • Via les fichiers Markdown sur GitHub.
  • Via le site généré Compodoc.

🔗 Lien vers la documentation GitHub Pages

CONFIGURATION

3 fichiers sont essentiels au bon fonctionnement :

  • tsconfig.doc.json
  • .compodocrc.json
  • docs/summary.json

Etape 1 : Installer Compodoc

Example :
pnpm add -DE @compodoc/compodoc@latest

Etape 2 :

  1. Créer tsconfig.doc.json (à la racine), afin que Compodoc exclu les fichiers de tests (.spec.ts) de la documentation....

  2. Créer le fichier .compodocrc.json =>

C'est la configuration principale de Compodoc (dossier de sortie, port, thème...)

💡 Une documentation complète est disponible ici... =>

👀 Compodoc Rules

  1. Créer le fichier summary.json dans un dossier docs à la racine =>

Celui-ci sert à définir la structure du menu latéral pour la documentation additionnelle (fichiers Markdown).

Etape 3 : Ajouter les scripts au package.json

Example :
{
  "scripts": {
    "doc": "node docs/_manage-doc.js serve",
    "doc:build": "node docs/_manage-doc.js build",
    "doc:ci": "node docs/_manage-doc.js build --keep",
  }
}

pnpm doc:build ne génère simplement que des fichiers statiques, ce script n'est utile que pour vérifier le build en local...Il n'est pas utilisé dans le déploiement !

Etape 4 : Lancer le serveur Compodoc en local =>

Example :
pnpm doc

🛠️ SCRIPT PERSONALISÉ

Pour résoudre le problème des liens relatifs qui diffèrent entre GitHub (./docs/file.md) et Compodoc (additional-documentation/file.html), un script de pré-traitement intelligent a été implémenté : docs/_manage-doc.j.

Ce script effectue les actions suivantes à chaque lancement :

  • Backup :
    Sauvegarder le README.md original.

  • Transformation :
    Remplacer les liens Markdown par des liens HTML compatibles Compodoc.

  • Verrouillage Git :
    Utiliser git update-index --assume-unchanged pour empêcher de commiter le fichier modifié par erreur.

  • Exécution :
    Lancer Compodoc avec les arguments appropriés.

  • Nettoyage :
    Restaurer le README.md original et nettoie le dossier de sortie (sauf en CI).

  • Sécurité :
    Utiliser des descripteurs de fichiers (fs.openSync) pour éviter les failles de type Race Condition.

💡 CodeQL signalerait une "Time-of-check to time-of-use (TOCTOU) race condition". En gros, il dirait : "Tu as vérifié que le fichier existait au début du script, mais entre ce moment-là et le moment où tu écris dedans (writeFileSync), un attaquant pourrait remplacer ce fichier par un lien symbolique malveillant."
C'est un risque très théorique pour un script de build local/CI...

CICD CICD

Le déploiement est géré par un Job dédié (documentation) dans le fichier .github/workflows/pipeline.yml.

Conditions d'exécution :

Le déploiement ne se lance que sur la branche main. Il nécessite que les jobs security et quality soient passés avec succès.

Fonctionnement du Job :

  1. Checkout du code.

  2. Installation des dépendances.

  3. Génération de la documentation via pnpm doc:ci avec injection dynamique du --base-href (nom du repo).

  4. Upload du dossier .documentation-output vers la branche orpheline gh-pages via l'action peaceiris/actions-gh-pages.

GITHUB PAGES GITHUB PAGES

La documentation est hébergée gratuitement via GitHub Pages. Elle est automatiquement mise à jour à chaque modification sur la branche main.

🔗 Lien vers la documentation GitHub Pages

DEPOT CONFIGURATION DU DEPOT

Pour que le site soit accessible, la configuration suivante a été appliquée dans les paramètres du dépôt GitHub :

  • Settings > Pages
  • Source : Deploy from a branch
  • Branch : gh-pages / (root)

🔗 Lien vers la configuration GitHub Pages

results matching ""

    No results matching ""