Generieren der Projektdokumentation mithilfe von GitHub Copilot

  • 6 Minuten

In der Projektdokumentation werden der Zweck, die Ziele und die Anforderungen eines Projekts beschrieben. Zum Erstellen der Projektdokumentation müssen Sie die Projektstruktur, die zugehörigen Komponenten und die Interaktion der Komponenten verstehen.

die Chatansicht von GitHub Copilot ist ein ideales Tool zum Generieren der Projektdokumentation, da sie die gesamte Projektstruktur analysieren und allgemeine Übersichten über das Projekt bereitstellen kann. Die Chatansicht kann auch verwendet werden, um bestimmte Arten von Dokumentationen zu generieren, z. B. README-Dateien, API-Verweise und andere projektbezogene Dokumente.

Sie können jeden der Chatansichtsmodi (Fragen, Agent oder Plan) verwenden, um Projektdokumentation zu generieren. Jeder Modus hat seine eigenen Stärken und Schwächen. Projektspezifikationen und andere Einschränkungen wirken sich darauf aus, welcher Modus verwendet werden soll.

Von Bedeutung

Wenn Sie die Chatansicht im Agentmodus verwenden, zählt jede Eingabeaufforderung, die Sie eingeben, als premium-Anforderung, multipliziert mit dem Multiplikator des Modells. GitHub Copilot kann mehrere Folgemaßnahmen ergreifen, um Ihre Aufgabe abzuschließen, aber diese Folgemaßnahmen zählen nicht zur Nutzung Ihrer Premium-Anfragen. Nur die von Ihnen eingegebenen Prompts werden in Rechnung gestellt. Die Gesamtzahl der verwendeten Premiumanfragen hängt davon ab, wie viele Aufforderungen Sie eingeben und welches Modell Sie auswählen.

Einrichten von Projektdokumentationsanforderungen

Dokumentationstypen und Inhaltsanforderungen hängen vom Projekt, den beabsichtigten Verbrauchern und den von der Organisation angenommenen Standards ab.

Die README.md können z. B. die folgenden Abschnitte enthalten:

  • Projekttitel: Der Name Ihres Projekts.
  • Beschreibung: Eine kurze Übersicht darüber, was das Projekt tut und warum es vorhanden ist.
  • Inhaltsverzeichnis: Optional, aber hilfreich für längere READMEs.
  • Installation: Anweisungen zum Installieren und Einrichten des Projekts.
  • Verwendung: Beispiele für die Verwendung des Projekts, einschließlich Codeausschnitte oder Screenshots.
  • Features: Eine Liste der wichtigsten Features oder Funktionen.
  • Konfiguration: Details zu konfigurationsoptionen oder Umgebungsvariablen.
  • Mitwirkend: Richtlinien für einen Beitrag zum Projekt.
  • Lizenz: Alle Lizenzen, die vom verteilten Projekt verwendet werden.
  • Danksagungen und Anerkennungen: Anerkennung von Mitwirkenden, Bibliotheken oder Ressourcen.
  • Kontakt: So erreichen Sie die Betreuer oder das Projektteam.
  • Changelog: Ein Verlauf von Änderungen und Aktualisierungen (manchmal mit einer separaten Datei verknüpft).

GitHub Copilot Chat kann Ihnen helfen, Projektdokumentationen zu generieren, die den spezifischen Anforderungen Ihres Projekts und seiner Projektbeteiligten entsprechen.

Verwenden des Ask-Agent-Modus zum Generieren der Projektdokumentation

Der Agent-Modus 'Ask' kann verwendet werden, um einen Workspace zu analysieren und dann Dokumentation zu generieren.

Verwenden Sie den folgenden Prozess, um die Projektdokumentation mithilfe des "Ask Agent"-Modus zu erstellen:

  1. Identifizieren Sie die Dokumentationsanforderungen und unterstützenden Ressourcen.

    • Identifizieren Sie die Dokumentationsanforderungen für Ihr Projekt. Identifizieren Sie die Arten der Dokumentation und die erforderlichen Dokumentabschnitte.

    • Identifizieren Sie die Ressourcen, die zum Generieren der Dokumentation erforderlich sind. Ihr Codearbeitsbereich könnte die einzige erforderliche Ressource sein. Möglicherweise müssen Sie dem Chat jedoch Kontext für Abschnitte wie "Mitwirken", "Gutschriften" und "Kontakt" hinzufügen.

  2. Öffnen Sie die Chatansicht, und starten Sie eine neue Chatsitzung mit dem Agent-Modus "Fragen".

  3. Fügen Sie der Chatsitzung Kontext hinzu.

    • Sie können der Chatsitzung Kontext hinzufügen, indem Sie Dateien aus der "Explorer"-Ansicht von Visual Studio Code in die "Chat"-Ansicht ziehen und dort ablegen. Sie können auch die Schaltfläche " Kontext anfügen " (Büroklammersymbol) verwenden.
    • Sie können externe Dateien im Code-Editor öffnen, um Ressourcen einzuschließen, die nicht Teil des Arbeitsbereichs sind, und diese verwenden, um mehr Kontext bereitzustellen. Sie können beispielsweise Markdowndateien öffnen, die Mitwirkenderichtlinien oder Kontaktinformationen enthalten, und dann die Schaltfläche " Kontext anfügen " verwenden, um sie dem Chatansichtskontext hinzuzufügen.

  4. Geben Sie eine Reihe von Eingabeaufforderungen ein, die Ihre Dokumentationsanforderungen untersuchen.

    Sie können den Agent-Modus "Fragen" verwenden, um den Arbeitsbereich zu analysieren und einen Chatsitzungsverlauf zu erstellen, der Ihre Dokumentationsanforderungen unterstützt. Wenn Sie Ihre Ziele beschreiben, können Sie den Kontext für die Chatsitzung einrichten. Wenn Sie Fragen stellen, die sich mit Ihren Anforderungen befassen, hilft GitHub Copilot dabei, die Informationen zu identifizieren, die benötigt werden, um die Dokumentation zu erstellen.

    Aktualisieren Sie den hinzugefügten Kontext nach Bedarf.

  5. Geben Sie eine Eingabeaufforderung ein, die nach der vorgeschlagenen Projektdokumentation fragt und die erforderlichen Abschnitte auflistet, die Sie im ersten Schritt identifiziert haben.

    Beispiel: "@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. Überprüfen Sie die vorgeschlagene Projektdokumentation, und verfeinern Sie die Ergebnisse bei Bedarf mithilfe neuer Eingabeaufforderungen.

  7. Verschieben Sie die vorgeschlagene Projektdokumentation in eine Projektdokumentationsdatei.

    Erstellen Sie beispielsweise eine README.md Datei im Stammverzeichnis des Arbeitsbereichs, und fügen Sie den vorgeschlagenen Inhalt in die Datei ein.

    Sie können den Agent-Modus "Fragen" verwenden, um Updates für bestimmte Abschnitte Ihres Projekts nach dem Erstellen des Dokuments vorzuschlagen oder andere GitHub Copilot Tools zur Unterstützung von Updates zu verwenden.

Verwenden des Planmodus zum Generieren der Projektdokumentation

Der Planmodus eignet sich am besten zum Erstellen eines detaillierten Implementierungsplans vor dem Generieren der Projektdokumentation. Der Planmodus analysiert die Codebasis, identifiziert die Dokumentationsanforderungen und erstellt einen schrittweisen Plan. Nachdem der Plan genehmigt wurde, können Sie ihn zur Ausführung an den Agentmodus übergeben.

Verwenden Sie den folgenden Prozess, um die Projektdokumentation zu generieren, z. B. eine README.md Datei, mithilfe des Planmodus:

  1. Identifizieren Sie die Dokumentationsanforderungen und unterstützenden Ressourcen.

  2. Öffnen Sie die Chatansicht, und starten Sie eine neue Chatsitzung mit dem Planmodus.

  3. Geben Sie eine Eingabeaufforderung ein, die Ihre Dokumentationsaufgabe beschreibt.

    Beispiel: "Ich muss eine README-Datei und unterstützende Dokumentation für dieses Projekt erstellen. Die INFODATEI sollte folgendes umfassen: Projekttitel, Beschreibung, Inhaltsverzeichnis, Installation, Verwendung, Features, Konfiguration und Lizenz."

  4. Überprüfen Sie den Implementierungsplan.

    Nach ein paar Momenten gibt der Plan-Agent einen Plan in der Chatansicht aus. Der Plan bietet eine allgemeine Zusammenfassung und eine Aufschlüsselung der Schritte, einschließlich aller offenen Fragen zur Klärung. Sie können mehrfach iterieren, um Anforderungen zu klären, den Umfang anzupassen oder Fragen zu beantworten.

  5. Nachdem der Plan abgeschlossen ist, wählen Sie "Implementierung starten " aus, um den Plan an den Agentmodus zu übergeben, oder wählen Sie "Im Editor öffnen " aus, um den Plan als Markdown-Datei für die spätere Verwendung zu speichern.

    Wenn Sie Start Implementation auswählen, wechselt GitHub Copilot zum Agentmodus und beginnt mit der Implementierung der Dokumentation basierend auf dem genehmigten Plan. Überprüfen Sie die generierten Dokumentationsdateien, und akzeptieren oder verwerfen Sie die Änderungen.

Verwenden des Agentmodus zum Generieren der Projektdokumentation

Der Agentmodus eignet sich am besten zum Generieren von Projektdokumentationen, die ein fundiertes Verständnis des Projekts erfordern. Der Agentmodus analysiert die gesamte Projektstruktur, bevor die Projektdokumentation generiert wird. Durch das Sammeln von Informationen aus mehreren Dateien und Ordnern kann der Agentmodus komplexe Beziehungen beschreiben und Verknüpfungen zwischen Dokumenten enthalten.

Verwenden Sie den folgenden Prozess, um die Projektdokumentation zu generieren, z. B. README.md Datei, mithilfe des Agentmodus:

  1. Identifizieren Sie die Dokumentationsanforderungen und unterstützenden Ressourcen.

  2. Öffnen Sie die Chatansicht, und starten Sie eine neue Chatsitzung mit dem Agentmodus.

  3. Fügen Sie der Chatsitzung Kontext hinzu.

    Chatteilnehmer sind im Agentmodus nicht verfügbar, daher können Sie sie nicht als Teil Ihrer Eingabeaufforderung angeben @workspace . Sie können jedoch der Chatsitzung Kontext hinzufügen, indem Sie #codebase sowie Arbeitsbereichsdateien und Ordner zum Chatkontext hinzufügen. Externe Dateien können in Visual Studio Code geöffnet und dann mithilfe der Schaltfläche Attach Context dem Chatkontext hinzugefügt werden.

  4. Geben Sie eine Eingabeaufforderung ein, um die beabsichtigte Projektdokumentation zu erstellen.

    Beispiel: "Generieren einer Sammlung von Projektdokumentationsdateien. Erstellen oder aktualisieren Sie die README.md-Datei des Arbeitsbereichs für dieses Repository. Erstellen oder aktualisieren Sie die UsageExamples.md Datei. Erstellen oder aktualisieren Sie die ChangeLog.md Datei. Fügen Sie Verknüpfungen zwischen den Dokumentationsdateien, referenzübergreifenden Klassen und Methoden ein, und sorgen Sie für Konsistenz in den Dokumenten."

  5. Überprüfen Sie die Dokumentdateien, und speichern oder verwerfen Sie die Aktualisierungen.

    Aktualisieren Sie die Datei mithilfe von Eingabeaufforderungen, um bestimmte Abschnitte bei Bedarf zu korrigieren oder zu verbessern.

Funktionen für den Agentmodus

Es gibt mehrere Dokumentationsaufgaben, bei denen der Agentmodus die beste Wahl ist.

  1. Mehrdateiige und dateiübergreifende Dokumentationsgenerierung.

    • Der Agentmodus kann die gesamte Projektstruktur analysieren, Informationen aus mehreren Dateien und Ordnern sammeln und Dokumentation generieren, die Inhalte über die Codebasis hinweg verknüpft und zusammenfasst. Beispielsweise wird ein vollständiger API-Verweis oder eine README generiert, die alle hauptkomponenten beschreibt.

  2. Automatisierte Projektanalyse und Zusammenfassung.

    • Der Agentmodus kann Aufgaben wie das Zusammenfassen der Architektur, das Identifizieren von Hauptklassen/Diensten und das Erstellen von Diagrammen oder Tabellen ausführen, die beziehungen zwischen Dateien und Komponenten verstehen müssen.

  3. Dynamische Inhaltsgenerierung (z. B. Verwendungsbeispiele, Klassentabellen)

    • Der Agentmodus kann das Projekt scannen, um Verwendungsbeispiele, Klassenverantwortungstabellen oder Listen öffentlicher APIs zu generieren.

  4. Chargendokumentations-Aufgaben.

    • Der Agentmodus kann eine Folge von Dokumentationsaufgaben (z. B. README aktualisieren, CONTRIBUTING.md erstellen, API-Dokumente generieren, Änderungsprotokoll aktualisieren) in einem Workflow ausführen.

  5. Intelligente Verknüpfung und Navigation.

    • Der Agentmodus kann Verknüpfungen zwischen Dokumentationsdateien, referenzübergreifenden Klassen und Methoden erstellen und die Konsistenz zwischen Dokumenten sicherstellen.

Der Agentmodus eignet sich ideal für projektweite, dateiübergreifende und kontextbezogene Dokumentationsaufgaben, die Analysen, Synthese und Koordination erfordern.

Zusammenfassung

GitHub Copilot können Sie bei der Erstellung von Projektdokumentationen unterstützen, die den spezifischen Anforderungen Ihres Projekts und seiner Projektbeteiligten entsprechen. Die Chatansicht kann verwendet werden, um Projektdokumentation in drei verschiedenen Modi zu generieren: Fragen, Agent und Plan. Jeder Modus hat seine eigenen Stärken und Schwächen, und der beste zu verwendende Modus hängt von der jeweiligen Aufgabe ab. Der Ask-Agent-Modus eignet sich am besten, um Fragen zu Ihren Codebasis- oder Technologiekonzepten zu stellen. Der Agentmodus eignet sich am besten zum Generieren von Projektdokumentationen, die ein fundiertes Verständnis des Projekts erfordern. Der Planmodus eignet sich am besten zum Erstellen eines detaillierten Implementierungsplans vor dem Generieren der Dokumentation, die dann zur Ausführung an den Agent-Modus übergeben werden kann.