diff --git a/obitests/.DS_Store b/obitests/.DS_Store new file mode 100644 index 0000000..4d505ca Binary files /dev/null and b/obitests/.DS_Store differ diff --git a/obitests/obitools/.DS_Store b/obitests/obitools/.DS_Store new file mode 100644 index 0000000..a6c2f80 Binary files /dev/null and b/obitests/obitools/.DS_Store differ diff --git a/prompt_documentation_globale.md b/prompt_documentation_globale.md new file mode 100644 index 0000000..abf26a4 --- /dev/null +++ b/prompt_documentation_globale.md @@ -0,0 +1,167 @@ +# Objectif +Documenter intégralement l'application OBITools (version 4, écrit en Go) en trois phases incrémentales, en utilisant les outils MCP fournis par cclsp. + +# Contexte +- Le code source est organisé en packages Go, chaque outil étant un exécutable avec un `main.go`. +- Vous avez accès à un serveur MCP (cclsp) qui expose les outils suivants (liste non exhaustive) : + - `find_definition(file, line, character)` : retourne la définition d’un symbole. + - `find_references(file, line, character)` : retourne toutes les références d’un symbole. + - `get_diagnostics(file)` : retourne les erreurs/warnings. + - `rename_symbol(file, line, character, new_name)` : permet de renommer (optionnel). +- Vous pouvez également exécuter des commandes shell pour lister les fichiers, lire/écrire des fichiers. +- Tous les fichiers de documentation seront stockés dans un répertoire `docs/` à la racine du projet, avec la structure suivante : + ``` + docs/ + phase1/ + / + .md + phase2/ + .md + phase3/ + .md + ``` + +# Instructions générales +- Avant de commencer, vérifiez que le répertoire `docs/phase1`, `docs/phase2`, `docs/phase3` existe (créez-les si nécessaire). +- Pour chaque phase, respectez le format Markdown demandé. +- N’hésitez pas à utiliser les outils MCP pour obtenir des informations précises sur les symboles (signatures, commentaires, types). +- Si un outil MCP nécessite des coordonnées (ligne, caractère), vous pouvez extraire ces informations en lisant le fichier source. +- Soyez méthodique : traitez un fichier/package/outil à la fois et sauvegardez immédiatement le résultat. + +--- + +## Phase 1 : Documentation par fichier Go (sauf `main.go`) + +**Objectif** : Pour chaque fichier `.go` qui n’est pas un `main.go` d’outil, générer un document Markdown décrivant son rôle, ses structures, ses fonctions principales et ses dépendances. + +**Étapes** : +1. Listez tous les fichiers `.go` du projet, en excluant ceux nommés `main.go` (ils seront traités en phase 3). Utilisez par exemple `find . -name "*.go" -not -name "main.go"`. +2. Pour chaque fichier : + a. Lisez son contenu (vous pouvez le faire via shell ou en utilisant l’outil `read_file` si disponible). + b. Utilisez les outils MCP pour extraire les informations suivantes : + - Pour chaque fonction publique (commençant par une majuscule) : appelez `find_definition` avec la ligne approximative où se trouve la fonction. Récupérez la signature et les commentaires associés. + - Pour les types (structs, interfaces) : faites de même. + c. Générez un document Markdown avec les sections : + ```markdown + # Fichier : `chemin/vers/fichier.go` + ## Rôle + (une phrase ou deux) + + ## Structures + - `NomStruct` : description, champs principaux + + ## Fonctions principales + - `NomFonction(paramètres) (retours)` : description + + ## Dépendances notables + - packages importés (externes ou internes) significatifs + ``` + d. Sauvegardez dans `docs/phase1//.md` (où `` est le nom du répertoire parent contenant le fichier, et `` le nom sans extension). + +**Exemple d’utilisation d’outil MCP** : +``` +# Pour obtenir la définition de la fonction `Align` dans `align/align.go` +# On suppose qu’elle se trouve approximativement ligne 120, colonne 1. +find_definition(file="align/align.go", line=120, character=1) +``` + +**Conseil** : Vous pouvez d’abord lister tous les symboles exportés d’un fichier en utilisant `go list` ou en analysant le code. Mais les outils MCP peuvent aussi vous aider. + +--- + +## Phase 2 : Agrégation par package + +**Objectif** : Pour chaque package (répertoire contenant au moins un fichier `.go` sauf `main.go`), créer un document Markdown qui synthétise l’ensemble des fichiers du package. + +**Étapes** : +1. Identifiez tous les packages (répertoires) qui contiennent des fichiers `.go` traités en phase 1. +2. Pour chaque package : + a. Lisez tous les fichiers `.md` de `docs/phase1//`. + b. Utilisez les outils MCP pour obtenir une vue d’ensemble des symboles exportés du package (par exemple, en interrogeant `find_references` sur un symbole clé ou en parcourant les définitions). + c. Générez un document Markdown avec : + ```markdown + # Package : `` + + ## Présentation + Description générale du package, son rôle dans OBITools (traitement de séquences, alignement, etc.) + + ## Structure interne + - Liste des fichiers principaux et leurs responsabilités (liens vers docs phase1) + - Flux de données ou interactions entre fichiers + + ## API publique + - **Types** : liste des types exportés avec brève description + - **Fonctions** : liste des fonctions exportées avec signature et rôle + - **Constantes/Variables** si pertinentes + + ## Exemple d’utilisation + (si possible, un extrait de code illustrant comment ce package est utilisé ailleurs) + ``` + d. Sauvegardez dans `docs/phase2/.md`. + +**Conseil** : Pour l’API publique, vous pouvez invoquer `find_definition` sur chaque symbole exporté (en vous basant sur les fichiers sources) pour obtenir les signatures exactes et les commentaires. + +--- + +## Phase 3 : Documentation des outils (exécutables) + +**Objectif** : Pour chaque outil (répertoire contenant un `main.go`), générer une documentation utilisateur complète, en utilisant les informations des packages documentés en phase 2. + +**Étapes** : +1. Trouvez tous les `main.go` du projet. Pour chacun, identifiez le nom de l’outil (généralement le nom du répertoire parent). +2. Pour chaque outil : + a. Lisez le `main.go` pour comprendre la logique globale et les options de ligne de commande (flags, cobra, etc.). + b. Identifiez tous les packages Go importés par l’outil (en analysant les imports du fichier). + c. Récupérez les documents `docs/phase2/.md` correspondants. + d. Utilisez les outils MCP pour explorer les fonctions appelées dans le `main.go` et comprendre leur rôle. + e. Générez un document Markdown : + ```markdown + # Outil : `` + + ## Résumé + Une ligne de description. + + ## Description + Explication détaillée de ce que fait l’outil, dans quel contexte l’utiliser, comment il traite les données (séquences, fichiers, etc.). + + ## Options + | Option | Type | Défaut | Description | + |--------|------|--------|-------------| + | `--flag` | string | "" | description extraite du code | + + ## Exemples + ```bash + # Exemple 1 : utilisation simple + outil -i input.fasta -o output.fasta + + # Exemple 2 : avec options avancées + outil --flag value ... + ``` + + ## Voir aussi + - [Package ``](../phase2/.md) + - [Package ``](../phase2/.md) + - Autres outils connexes + ``` + f. Sauvegardez dans `docs/phase3/.md`. + +**Conseil** : Pour extraire les options, examinez le code qui utilise `flag` ou `cobra`. Vous pouvez aussi utiliser `go doc` sur le package principal, mais les outils MCP vous permettront de suivre les références aux symboles. + +--- + +# Validation et finalisation +- Après avoir généré tous les documents, vérifiez que la documentation phase3 inclut bien des liens fonctionnels vers les documents phase2. +- Si certains packages ne sont pas documentés (parce que leurs fichiers n’ont pas été traités en phase1), repérez les oublis et corrigez. +- Vous pouvez générer un index global dans `docs/README.md` listant tous les packages et outils avec leurs descriptions. + +--- + +# Consignes d’exécution +- Travaillez de manière séquentielle : terminez une phase avant de passer à la suivante. +- Pour chaque fichier/package/outil, utilisez les outils MCP de manière parcimonieuse mais exhaustive. +- Si un outil MCP échoue (par exemple, coordonnées incorrectes), ajustez en relisant le fichier source pour trouver la bonne ligne/colonne. +- Enregistrez les résultats immédiatement après génération pour éviter les pertes. + +Maintenant, commencez par la phase 1. Listez tous les fichiers `.go` (hors main.go) et générez la documentation pour le premier fichier. + +