Generer projektdokumentation ved hjælp af GitHub Copilot

I projektdokumentationen beskrives formålet med, målene og kravene til et projekt. Hvis du vil oprette projektdokumentationen, skal du forstå projektstrukturen, dens komponenter, og hvordan komponenterne interagerer med hinanden.

GitHub Copilot's Chat-visning er et ideelt værktøj til at generere projektdokumentation, fordi den kan analysere hele projektstrukturen og give overordnede oversigter over projektet. Chatvisningen kan også bruges til at generere bestemte typer dokumentation, f.eks. README-filer, API-referencer og andre projektrelaterede dokumenter.

Du kan bruge hver af chatvisningstilstandene (Ask, Agent eller Plan) til at generere projektdokumentation. Hver tilstand har sine egne styrker og svagheder. Projektspecifikationer og andre begrænsninger påvirker, hvilken tilstand der skal bruges.

Fastlæg krav til projektdokumentation

Dokumentationstyper og krav til indhold afhænger af projektet, de tilsigtede forbrugere og de standarder, der er vedtaget af organisationen.

README.md kan f.eks. indeholde følgende afsnit:

• Projekttitel: Navnet på projektet.
• Beskrivelse: En kort oversigt over, hvad projektet gør, og hvorfor det findes.
• Indholdsfortegnelse: Valgfri, men nyttig for længere READMEs.
• Installation: Instruktioner til, hvordan du installerer og konfigurerer projektet.
• Anvendelse: Eksempler på, hvordan du bruger projektet, herunder kodestykker eller skærmbilleder.
• Funktioner: En liste over vigtige funktioner eller funktioner.
• Konfiguration: Oplysninger om alle konfigurationsindstillinger eller miljøvariabler.
• Bidrag: Retningslinjer for bidrag til projektet.
• Licens: Alle licenser, der bruges af det distribuerede projekt.
• Kreditter og anerkendelser: Anerkendelse af bidragydere, biblioteker eller anvendte ressourcer.
• Kontakt: Sådan kontakter du vedligeholderne eller projektteamet.
• Changelog: En oversigt over ændringer og opdateringer (nogle gange sammenkædet med en separat fil).

GitHub Copilot Chat kan hjælpe dig med at generere projektdokumentation, der opfylder de specifikke behov hos dit projekt og dets interessenter.

Brug Ask agent-tilstanden til at generere projektdokumentation

Ask agent-tilstanden kan bruges til at analysere et arbejdsområde og derefter generere dokumentation.

Brug følgende proces til at generere projektdokumentation ved hjælp af Ask agent-tilstanden:

1. Identificer dokumentationskravene og de understøttende ressourcer.

   • Identificer dokumentationskravene til dit projekt. Identificer dokumentationstyperne og de påkrævede dokumentsektioner.

   • Identificer de ressourcer, der kræves for at generere dokumentationen. Kodearbejdsområdet kan være den eneste påkrævede ressource. Du skal dog muligvis føje kontekst til chatten for sektioner som "Bidrag", "Kreditter" og "Kontakt".

2. Åbn chatvisningen og start en ny chatsession i Ask agent-tilstanden.

3. Føj kontekst til chatsessionen.

   • Du kan tilføje kontekst til chatsessionen ved at trække og slippe filer fra Visual Studio Code's EXPLORER-visning ind i chat-visningen. Du kan også bruge knappen Attach Context , som er ikonet (papirclips-ikon).
   • Du kan åbne eksterne filer i kodeeditoren for at inkludere ressourcer, der ikke er en del af arbejdsområdet, og bruge dem til at give mere kontekst. For eksempel kan du åbne markdown-filer, der indeholder bidragyderretningslinjer eller kontaktoplysninger, og derefter bruge knappen Vedhæft Kontekst til at tilføje dem til Chat-visningskonteksten.

4. Angiv en række prompter, der undersøger dokumentationskravene.

   Du kan bruge Ask agent-tilstanden til at analysere arbejdsområdet og opbygge en chat-sessionshistorik, der understøtter dine dokumentationskrav. Beskrivelse af dine mål kan hjælpe med at etablere kontekst for chatsessionen. At stille spørgsmål, der adresserer dine krav, hjælper GitHub Copilot med at identificere de oplysninger, der er nødvendige for at generere dokumentationen.

   Opdater den tilføjede kontekst efter behov.

5. Angiv en prompt, hvor du bliver bedt om at angive forslag til projektdokumentation med en liste over de påkrævede sektioner, som du identificerede i det første trin.

   For eksempel: "/explain #codebase 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. Gennemse den foreslåede projektdokumentation, og afgræns resultaterne ved hjælp af nye prompter, hvis det er nødvendigt.

7. Flyt den foreslåede projektdokumentation til en projektdokumentationsfil.

   Du kan f.eks. oprette en README.md fil i roden af arbejdsområdet og indsætte det foreslåede indhold i filen.

   Du kan bruge Ask agent-tilstanden til at foreslå opdateringer til specifikke dele af dit projekt efter at have oprettet dokumentet, eller bruge andre GitHub Copilot værktøjer til at hjælpe med opdateringer.

Brug Plan-tilstanden til at generere projektdokumentation

Plantilstand er bedst til at lave en detaljeret implementeringsplan, før projektdokumentation genereres. Plan-tilstanden analyserer kodebasen, identificerer dokumentationskrav og udarbejder en trin-for-trin plan. Når planen er godkendt, kan du overdrage den til agent-mode til udførelse.

Brug følgende proces til at generere projektdokumentation, såsom en README.md-fil, ved hjælp af Plan-tilstanden:

1. Identificer dokumentationskravene og de understøttende ressourcer.

2. Åbn chatvisningen og start en ny chatsession i Plan-tilstanden.

3. Indtast en prompt, der beskriver din dokumentationsopgave.

   For eksempel: "Jeg skal oprette en README-fil og understøttende dokumentation for dette projekt. README'en bør indeholde: Projekttitel, Beskrivelse, Indholdsfortegnelse, Installation, Brug, Funktioner, Konfiguration og Licens."

4. Gennemse implementeringsplanen.

   Efter et par øjeblikke viser Planagenten en plan i Chat-visningen. Planen giver et overordnet resumé og en gennemgang af trinene, inklusive eventuelle åbne spørgsmål til afklaring. Du kan iterere flere gange for at præcisere krav, justere scope eller besvare spørgsmål.

5. Når planen er færdig, vælg Start Implementering for at overdrage planen til agenttilstand, eller vælg Åben i Editor for at gemme planen som en Markdown-fil til senere brug.

   Når du vælger Start Implementering, skifter GitHub Copilot til agenttilstand og begynder at implementere dokumentationen baseret på den godkendte plan. Gennemgå de genererede dokumentationsfiler og accepter eller kasser ændringerne.

Brug agenttilstanden til at generere projektdokumentation

Agenttilstand er bedst til at generere projektdokumentation, der kræver en detaljeret forståelse af projektet. Agenttilstand analyserer hele projektstrukturen, før den genererer projektdokumentation. Ved at indsamle oplysninger fra flere filer og mapper kan agenttilstand beskrive komplekse relationer og inkludere links mellem dokumenter.

Brug følgende proces til at generere projektdokumentation, såsom README.md fil, ved hjælp af agent-tilstand:

1. Identificer dokumentationskravene og de understøttende ressourcer.

2. Åbn chatvisningen, og start en ny chatsession ved hjælp af agenttilstanden.

3. Føj kontekst til chatsessionen.

   Chatdeltagere er ikke tilgængelige i agenttilstand, så du kan ikke angive @terminal som en del af din prompt. Du kan dog føje kontekst til chatsessionen ved hjælp #codebase af og ved at føje arbejdsområdefiler og -mapper til chatkonteksten. Eksterne filer kan åbnes i Visual Studio Code og derefter tilføjes til chatkonteksten ved hjælp af knappen Attach Context.

4. Angiv en prompt for at oprette den ønskede projektdokumentation.

   For eksempel: "Generér en samling af projektdokumentationsfiler. Opret eller opdater arbejdsområdet README.md fil til dette lager. Opret eller opdater filen UsageExamples.md. Opret eller opdater filen ChangeLog.md. Medtag links mellem dokumentationsfilerne, krydshenvisningsklasser og -metoder, og sørg for ensartethed på tværs af dokumenterne."

5. Gennemse dokumentfilerne, og gem eller fjern derefter opdateringerne.

   Opdater filen ved hjælp af prompts for at rette eller forbedre bestemte sektioner, hvis det er nødvendigt.

Funktioner i agenttilstand

Der er flere dokumentationsopgaver, hvor agenttilstand er det bedste valg.

1. Oprettelse af dokumentation med flere filer og på tværs af filer.

   • Agenttilstand kan analysere hele projektstrukturen, indsamle oplysninger fra flere filer og mapper og generere dokumentation, der linker og opsummerer indhold på tværs af kodebasen. Du kan f.eks. generere en komplet API-reference eller en README, der beskriver alle hovedkomponenter.

2. Automatiseret projektanalyse og opsummering.

   • Agenttilstand kan udføre opgaver som f.eks. at opsummere arkitekturen, identificere hovedklasser/tjenester og producere diagrammer eller tabeller, der kræver forståelse af relationer mellem filer og komponenter.

3. Generering af dynamisk indhold (f.eks. brugseksempler, klassetabeller)

   • Agenttilstand kan scanne projektet for at generere forbrugseksempler, tabeller over klasseansvar eller lister over offentlige API'er.

4. Batchdokumentationsopgaver.

   • Agenttilstand kan udføre en sekvens af dokumentationsopgaver (f.eks. opdatere VIGTIGT, oprette CONTRIBUTING.md, generere API-dokumentation, opdatere ændringslog) i én arbejdsproces.

5. Intelligent sammenkædning og navigation.

   • Agenttilstand kan oprette links mellem dokumentationsfiler, krydshenvisningsklasser og -metoder og sikre ensartethed på tværs af dokumenter.

Agenttilstand er ideel til dokumentationsopgaver, der kræver analyse, syntese og koordinering, som omfatter flere filer og kontekstafhængig dokumentation.

Resumé

GitHub Copilot kan hjælpe dig med at generere projektdokumentation, der opfylder de specifikke behov hos dit projekt og dets interessenter. Chat-visningen kan bruges til at generere projektdokumentation i tre forskellige tilstande: Ask, Agent og Plan. Hver tilstand har sine egne styrker og svagheder, og den bedste tilstand at bruge afhænger af den specifikke opgave, der er ved hånden. Ask agent-tilstanden er bedst til at stille spørgsmål om din kodebase eller teknologiske koncepter. Agent-tilstanden er bedst til at generere projektdokumentation, der kræver en dybdegående forståelse af projektet. Plan-tilstanden er bedst til at lave en detaljeret implementeringsplan, før dokumentation genereres, som derefter kan overdrages til Agent-tilstand til eksekvering.