Générer la documentation du projet à l’aide de GitHub Copilot

  • 6 minutes

La documentation du projet décrit l’objectif, les objectifs et les exigences d’un projet. Pour créer la documentation du projet, vous devez comprendre la structure du projet, ses composants et la façon dont les composants interagissent entre eux.

L'affichage Chat de GitHub Copilot est un outil idéal pour générer la documentation du projet, car il peut analyser l'ensemble de la structure du projet et fournir une vue d'ensemble du projet. La vue Conversation peut également être utilisée pour générer des types spécifiques de documentation, tels que des fichiers README, des références d’API et d’autres documents liés au projet.

Vous pouvez utiliser chacun des modes d’affichage de conversation (Demande, Agent ou Plan) pour générer la documentation du projet. Chaque mode a ses propres forces et faiblesses. Les spécifications de projet et d’autres contraintes affectent le mode à utiliser.

Important

Lorsque vous utilisez la vue Conversation en mode agent, chaque instruction que vous entrez compte comme une requête premium, multipliée par le multiplicateur du modèle. GitHub Copilot peut effectuer plusieurs actions de suivi pour accomplir la tâche, mais ces actions de suivi ne comptent pas dans votre utilisation des demandes Premium. Seuls les prompts que vous saisissez sont facturés. Le nombre total de requêtes Premium utilisées dépend du nombre d’invites que vous entrez et du modèle sélectionné.

Établir des exigences en matière de documentation de projet

Les types de documentation et les exigences de contenu dépendent du projet, des consommateurs prévus et des normes adoptées par l’organisation.

Par exemple, les README.md peuvent inclure les sections suivantes :

  • Titre du projet : nom de votre projet.
  • Description : brève vue d’ensemble de ce que fait le projet et de la raison pour laquelle il existe.
  • Table des matières : facultatif, mais utile pour les éléments README plus longs.
  • Installation : instructions sur l’installation et la configuration du projet.
  • Utilisation : exemples d’utilisation du projet, y compris des extraits de code ou des captures d’écran.
  • Fonctionnalités : liste des fonctionnalités ou fonctionnalités clés.
  • Configuration : détails sur les options de configuration ou les variables d’environnement.
  • Contribution : Instructions pour contribuer au projet.
  • Licence : toutes les licences utilisées par le projet distribué.
  • Crédits et accusés de réception : reconnaissance des contributeurs, bibliothèques ou ressources utilisées.
  • Contact : Comment atteindre les maintenances ou l’équipe de projet.
  • Journal des modifications : historique des modifications et des mises à jour (parfois lié à un fichier distinct).

GitHub Copilot Chat peut vous aider à générer la documentation du projet qui répond aux besoins spécifiques de votre projet et de ses parties prenantes.

Utiliser le mode Demander à l’agent pour générer la documentation du projet

Le mode Demander à l’agent peut être utilisé pour analyser un espace de travail, puis générer de la documentation.

Utilisez le processus suivant pour générer la documentation du projet à l’aide du mode Demander à l’agent :

  1. Identifiez les exigences de documentation et les ressources de prise en charge.

    • Identifiez les exigences en matière de documentation pour votre projet. Identifiez les types de documentation et les sections de document requises.

    • Identifiez les ressources requises pour générer la documentation. Votre espace de travail de code peut être la seule ressource requise. Toutefois, vous devrez peut-être ajouter du contexte à la conversation pour les sections telles que « Contribution », « Crédits » et « Contact ».

  2. Ouvrez la vue Conversation et démarrez une nouvelle session de conversation à l’aide du mode Demander à l’agent.

  3. Ajoutez un contexte à la session de conversation.

    • Vous pouvez ajouter du contexte à la session de conversation en faisant glisser et en déposant des fichiers de la vue EXPLORATEUR de Visual Studio Code dans la vue de chat. Vous pouvez également utiliser le bouton Attacher le contexte (icône paperclip).
    • Vous pouvez ouvrir des fichiers externes dans l’éditeur de code pour inclure des ressources qui ne font pas partie de l’espace de travail et les utiliser pour fournir davantage de contexte. Par exemple, vous pouvez ouvrir des fichiers Markdown qui contiennent des instructions de contributeur ou des informations de contact, puis utiliser le bouton Attacher le contexte pour les ajouter au contexte de vue conversation.

  4. ** Entrez une série d'instructions explorant vos exigences en matière de documentation.

    Vous pouvez utiliser le mode Demander à l’agent pour analyser l’espace de travail et créer un historique de session de conversation qui prend en charge vos besoins en documentation. La description de vos objectifs peut vous aider à établir le contexte de la session de conversation. Poser des questions qui répondent à vos besoins aide GitHub Copilot identifier les informations nécessaires à la génération de la documentation.

    Actualisez le contexte ajouté si nécessaire.

  5. Entrez une requête qui demande une documentation proposée de projet, répertoriant les sections requises identifiées à la première étape.

    Par exemple : « @workspace /explain I need help creating a README file that can be used in the GitHub repository for this workspace. The file should be formatted as markdown. The README file needs to include the following sections: Project Title, Description, Table of Contents, Installation, Usage, Features, Configuration, and License. »

  6. Examinez la documentation de projet suggérée et affinez les résultats à l’aide de nouvelles invites si nécessaire.

  7. Déplacez la documentation suggérée du projet dans un fichier de documentation de projet.

    Par exemple, créez un fichier README.md à la racine de l’espace de travail et insérez le contenu suggéré dans le fichier.

    Vous pouvez utiliser le mode Demander à l’agent pour suggérer des mises à jour pour des sections spécifiques de votre projet après avoir créé le document, ou utiliser d’autres outils de GitHub Copilot pour faciliter les mises à jour.

Utiliser le mode Plan pour générer la documentation du projet

Le mode plan est idéal pour créer un plan d’implémentation détaillé avant de générer la documentation du projet. Le mode Plan analyse la base de code, identifie les exigences de documentation et produit un plan pas à pas. Une fois le plan approuvé, vous pouvez le remettre en mode agent pour l’exécution.

Utilisez le processus suivant pour générer la documentation du projet, telle qu’un fichier README.md, à l’aide du mode Plan :

  1. Identifiez les exigences de documentation et les ressources de prise en charge.

  2. Ouvrez l’affichage Conversation et démarrez une nouvelle session de conversation à l’aide du mode Plan.

  3. Saisissez un texte décrivant votre tâche de documentation.

    Par exemple : « Je dois créer un fichier README et une documentation de prise en charge pour ce projet. Le fichier README doit inclure : Titre du projet, Description, Table des matières, Installation, Utilisation, Fonctionnalités, Configuration et Licence. »

  4. Passez en revue le plan d’implémentation.

    Après quelques instants, l’agent Plan génère un plan dans la vue Conversation. Le plan fournit un résumé général et une répartition des étapes, y compris toutes les questions ouvertes à des fins de clarification. Vous pouvez itérer plusieurs fois pour clarifier les exigences, ajuster l’étendue ou répondre aux questions.

  5. Une fois le plan terminé, sélectionnez Démarrer l’implémentation pour remettre le plan en mode agent, ou sélectionnez Ouvrir dans l’Éditeur pour enregistrer le plan en tant que fichier Markdown pour une utilisation ultérieure.

    Lorsque vous sélectionnez Start Implementation, GitHub Copilot bascule vers le mode agent et commence à implémenter la documentation en fonction du plan approuvé. Passez en revue les fichiers de documentation générés et acceptez ou ignorez les modifications.

Utiliser le mode agent pour générer la documentation du projet

Le mode Agent est idéal pour générer la documentation du projet qui nécessite une compréhension approfondie du projet. Le mode agent analyse l’ensemble de la structure du projet avant de générer la documentation du projet. En collectant des informations à partir de plusieurs fichiers et dossiers, le mode agent peut décrire des relations complexes et inclure des liens entre des documents.

Utilisez le processus suivant pour générer la documentation du projet, telle que README.md fichier, à l’aide du mode agent :

  1. Identifiez les exigences de documentation et les ressources de prise en charge.

  2. Ouvrez la vue Conversation et démarrez une nouvelle session de conversation à l’aide du mode agent.

  3. Ajoutez un contexte à la session de conversation.

    Les participants à la conversation ne sont pas disponibles en mode agent. Vous ne pouvez donc pas spécifier @workspace dans le cadre de votre invite. Toutefois, vous pouvez ajouter du contexte à la session de conversation à l’aide #codebase et en ajoutant des fichiers et dossiers d’espace de travail au contexte de conversation. Les fichiers externes peuvent être ouverts dans Visual Studio Code, puis ajoutés au contexte de conversation à l’aide du bouton Attach Context.

  4. Entrez une requête pour créer la documentation prévue du projet.

    Par exemple : « Générer une collection de fichiers de documentation de projet. Créez ou mettez à jour le fichier README.md de l’espace de travail pour ce référentiel. Créez ou mettez à jour le fichier UsageExamples.md. Créez ou mettez à jour le fichier ChangeLog.md. Incluez des liens entre les fichiers de documentation, les classes de référence croisée et les méthodes, et assurez-vous de la cohérence entre les documents.

  5. Passez en revue les fichiers du document, puis enregistrez ou ignorez les mises à jour.

    Mettez à jour le fichier à l’aide d’invites pour corriger ou améliorer des sections spécifiques si nécessaire.

Fonctionnalités du mode Agent

Il existe plusieurs tâches de documentation où le mode agent est le meilleur choix.

  1. Génération de documentation multi-fichiers et inter-fichiers.

    • Le mode Agent peut analyser l’ensemble de la structure du projet, collecter des informations à partir de plusieurs fichiers et dossiers, et générer de la documentation qui lie et résume le contenu dans la base de code. Par exemple, la génération d’une référence d’API complète ou d’un fichier README qui décrit tous les principaux composants.

  2. Analyse et synthèse automatisées des projets.

    • Le mode agent peut effectuer des tâches telles que la synthèse de l’architecture, l’identification des classes/services principales et la production de diagrammes ou de tables qui nécessitent une compréhension des relations entre les fichiers et les composants.

  3. Génération de contenu dynamique (par exemple, exemples d’utilisation, tables de classes)

    • Le mode Agent peut analyser le projet pour générer des exemples d’utilisation, des tables de responsabilité de classe ou des listes d’API publiques.

  4. Tâches de documentation par lots.

    • Le mode agent peut exécuter une séquence de tâches de documentation (par exemple, mettre à jour README, créer CONTRIBUTING.md, générer des documents d’API, mettre à jour le journal des modifications) dans un flux de travail.

  5. Liaison intelligente et navigation.

    • Le mode agent peut créer des liens entre des fichiers de documentation, des classes et des méthodes de référence croisée, et garantir la cohérence entre les documents.

Le mode agent est idéal pour les tâches de documentation à l’échelle du projet, multi-fichiers et prenant en charge le contexte qui nécessitent une analyse, une synthèse et une coordination.

Résumé

GitHub Copilot pouvez vous aider à générer la documentation du projet qui répond aux besoins spécifiques de votre projet et de ses parties prenantes. La vue Chat peut être utilisée pour générer la documentation de projet en trois modes différents : Mode Demande, Agent et Mode Plan. Chaque mode a ses propres forces et faiblesses, et le meilleur mode à utiliser dépend de la tâche spécifique à portée de main. Le mode Agent de questions est idéal pour poser des questions sur votre base de code ou sur des concepts technologiques. Le mode Agent est idéal pour générer la documentation du projet qui nécessite une compréhension approfondie du projet. Le mode Plan est idéal pour créer un plan d’implémentation détaillé avant de générer de la documentation, qui peut ensuite être remis au mode Agent pour l’exécution.