---
name: generateur-doc
description: Génère un rapport structuré (fonctions/classes/méthodes publiques, signatures, résumé de docstring) à partir de code source Python ou Rust — stdlib pur, zéro appel réseau.
theme: outillage-developpement
langages_cibles: python
---

# generateur-doc

## Objectif

Produire une documentation structurée (Markdown ou JSON) à partir d'un
fichier ou d'un dossier de code source Python/Rust : fonctions, classes,
méthodes, signatures complètes, premier résumé de docstring/commentaire de
doc, numéro de ligne. Pensé pour accélérer la rédaction des futurs skills
eux-mêmes (SKILL.md, README) à partir du code réellement écrit, plutôt que
de la documentation reconstituée de mémoire.

## Pourquoi Python (et pas un autre langage) ?

- **Python en entrée** : le module `ast` de la stdlib fournit une analyse
  syntaxique déterministe et fiable à 100% (pas de regex fragile) — aucune
  autre approche stdlib n'apporterait une garantie équivalente sur du code
  Python lui-même.
- **Rust en entrée** : contrairement à Python, il n'existe aucun analyseur
  syntaxique Rust dans la stdlib d'aucun langage sans dépendance tierce
  (la crate `syn` existe mais violerait la règle "zéro dépendance"). Une
  extraction structurelle par motif texte (regex) est donc le seul choix
  compatible avec la souveraineté totale — documentée comme limite connue
  ci-dessous, pas cachée.
- **Outil lui-même en Python** : permet de traiter les DEUX langages cibles
  (Python natif via `ast`, Rust via regex) dans un seul script sans
  compilation, cohérent avec les 2 autres skills Python du projet.

## Garanties de sécurité

- **Contenu analysé = donnée inerte.** Pour Python, `ast.parse` construit un
  arbre syntaxique sans jamais exécuter le code source (contrairement à
  `exec`/`eval`, jamais utilisés ici) — un fichier contenant du code
  malveillant ou un texte de docstring qui ressemble à une instruction pour
  un assistant IA n'est jamais interprété comme tel, seulement analysé
  structurellement.
- **Aucune donnée transmise à l'extérieur** — 100% local, 0 appel réseau,
  0 dépendance tierce.
- Les résumés de docstring/doc-commentaire sont tronqués (`longueur_max`) et
  insérés tels quels dans le rapport — un futur usage qui afficherait ce
  rapport dans une interface web devrait les échapper en HTML (hors périmètre
  de ce skill, qui ne produit que du Markdown/JSON local).

## Gestion d'erreur exhaustive

`erreurs.py` : `ErreurCibleIntrouvable` (chemin absent), `ErreurCibleNonAccessible`
(permission refusée), `ErreurLangageNonSupporte` (extension hors `.py`/`.rs`
en mode fichier unique), `ErreurAnalyseSyntaxique` (SyntaxError Python réelle
— fatale en mode fichier unique, collectée sans interrompre le scan en mode
dossier), `ErreurEcritureRapport`. `main()` traite chaque catégorie dans une
branche `except` dédiée avec un code de sortie distinct, plus un dernier
recours nommé (`ErreurInterne`, code 99) — jamais un `except Exception: pass`
silencieux.

## Mode d'emploi

**Analyser un fichier unique (rapport Markdown, sortie standard) :**

```bash
python3 generateur_doc.py /chemin/vers/mon-projet/mon_module.py
```

**Analyser un dossier entier, rapport JSON écrit sur disque :**

```bash
python3 generateur_doc.py /chemin/vers/mon-projet/src \
  --format json --out rapports/mon-rapport.json
```

**Résultat réel obtenu lors de la validation de ce skill** : exécuté sur le
dossier `src/` d'un projet Rust d'environ 650 fichiers (0.5 seconde) —
657 fichiers analysés, 2100 fonctions publiques et 665 struct/enum publics
détectés, 0 erreur de syntaxe. **1 bug réel trouvé et corrigé pendant cette
validation** : les signatures de fonction étalées sur plusieurs lignes
(patron très fréquent dans ce projet, ex. `pub fn f(\n    arg: T,\n) -> R`)
n'étaient pas détectées par le premier jet du regex mono-ligne — corrigé par
`joindre_signature_multiligne()` (comptage de profondeur de parenthèses
caractère par caractère, pas une simple recherche de sous-chaîne — un ';'
interne à un type comme `&[u8; 32]` avait initialement fait tronquer la
signature à tort lors de la première correction, corrigé une seconde fois en
séparant strictement "fermeture de la liste d'arguments" et "recherche du
terminateur `{`/`;`"). Test de non-régression dédié dans `tests_locaux/`.

**Options communes :**

- `--format` : `md` (défaut, lisible) | `json` (structuré, pour automatisation)
- `--out` : chemin de sortie (défaut : stdout)

**Prérequis :** aucune installation — Python 3 standard suffit (testé en 3.12,
`ast.unparse` requiert Python ≥ 3.9).

## Limites connues (honnêteté de l'outil, pas de sur-promesse)

- **Rust : extraction par motif texte, pas un vrai parseur.** Ne gère que les
  fonctions/struct/enum `pub` de premier niveau (pas les impl blocks internes,
  pas les macros qui génèrent du code, pas les traits). Un type de retour
  contenant lui-même des accolades (ex. un type de fonction complexe) pourrait
  tronquer la signature de façon incorrecte — cas non rencontré dans la
  validation réelle mais théoriquement possible.
- **Python : seuls les éléments de niveau module et les méthodes de classe
  directe sont documentés** — les fonctions imbriquées (closures) et les
  classes imbriquées ne sont pas descendues plus d'un niveau, par choix (un
  rapport trop profond serait moins lisible qu'utile pour l'usage visé :
  documenter l'API publique d'un module).
- Le résumé de docstring/doc-commentaire ne prend que la première ligne —
  une docstring multi-paragraphes n'est pas reproduite intégralement (choix
  délibéré, cohérent avec l'objectif "aperçu", pas "documentation complète").