Generování dokumentace k projektu pomocí GitHub Copilot

Dokumentace k projektu popisuje účel, cíle a požadavky projektu. Pokud chcete vytvořit dokumentaci k projektu, musíte porozumět struktuře projektu, jeho komponentám a vzájemné interakci s komponentami.

Náhled chat GitHub Copilot je ideální nástroj pro generování dokumentace k projektu, protože dokáže analyzovat celou strukturu projektu a poskytovat přehledy vysoké úrovně. Zobrazení chatu se dá použít také ke generování konkrétních typů dokumentace, jako jsou soubory README, reference k rozhraní API a další dokumenty související s projektem.

Ke generování dokumentace k projektu můžete použít každý režim zobrazení chatu (Ask, Agent nebo Plan). Každý režim má své vlastní silné a slabé stránky. Specifikace projektu a další omezení ovlivňují, který režim se má použít.

Stanovení požadavků na dokumentaci k projektu

Typy dokumentace a požadavky na obsah závisí na projektu, zamýšlených uživatelích a standardech přijatých organizací.

Například README.md může obsahovat následující části:

• Název projektu: Název projektu.
• Popis: Stručný přehled toho, co projekt dělá a proč existuje.
• Obsah: Nepovinný, ale užitečný pro delší dokumenty README.
• Instalace: Pokyny k instalaci a nastavení projektu.
• Použití: Příklady použití projektu, včetně fragmentů kódu nebo snímků obrazovky.
• Funkce: Seznam klíčových funkcí.
• Konfigurace: Podrobnosti o všech možnostech konfigurace nebo proměnných prostředí.
• Přispívání: Pokyny pro přispívání do projektu.
• Licence: Všechny licence používané distribuovaným projektem.
• Kredity a potvrzení: Uznání přispěvatelů, knihoven nebo použitých prostředků
• Kontakt: Jak kontaktovat správce nebo projektový tým.
• Protokol změn: Historie změn a aktualizací (někdy propojených s samostatným souborem).

GitHub Copilot Chat vám může pomoct vygenerovat dokumentaci k projektu, která splňuje konkrétní potřeby projektu a jejích zúčastněných stran.

Generování dokumentace k projektu pomocí režimu Zeptejte se agenta

K analýze pracovního prostoru a následnému vygenerování dokumentace můžete použít režim agenta Ask.

Pomocí následujícího postupu vygenerujte dokumentaci k projektu pomocí režimu agenta Ask:

1. Identifikujte požadavky na dokumentaci a podpůrné prostředky.

   • Identifikujte požadavky na dokumentaci pro váš projekt. Identifikujte typy dokumentace a požadované části dokumentu.

   • Identifikujte prostředky potřebné k vygenerování dokumentace. Váš pracovní prostor kódu může být jediným požadovaným prostředkem. Možná ale budete muset do chatu přidat kontext pro oddíly, jako je "Přispívání", "Kredity" a "Kontakt".

2. Otevřete zobrazení chatu a spusťte novou relaci chatu pomocí režimu Zeptejte se agenta.

3. Přidejte do chatovací relace kontext.

   • Do relace chatu můžete přidat kontext přetažením souborů z zobrazení Průzkumníka Visual Studio Code do zobrazení Chat. Můžete také použít tlačítko Připojit kontext (ikona sponky).
   • V editoru kódu můžete otevřít externí soubory, abyste zahrnuli prostředky, které nejsou součástí pracovního prostoru, a použít je k zajištění dalšího kontextu. Můžete například otevřít soubory Markdownu, které obsahují pokyny pro přispěvatele nebo kontaktní informace, a pak je pomocí tlačítka Připojit kontext přidat do kontextu zobrazení chatu.

4. Zadejte řadu výzev, které prošetřují požadavky na dokumentaci.

   Pomocí režimu Zeptejte se agenta můžete analyzovat pracovní prostor a vytvořit historii chatu, která podporuje vaše požadavky na dokumentaci. Popis vašich cílů vám může pomoct vytvořit kontext pro chatovací relaci. Kladení otázek, které řeší vaše požadavky, pomáhá GitHub Copilot identifikovat informace potřebné k vygenerování dokumentace.

   Podle potřeby aktualizujte přidaný kontext.

5. Zadejte výzvu, která požádá o navrženou dokumentaci k projektu a zobrazí se seznam požadovaných oddílů, které jste identifikovali v prvním kroku.

   Příklad: "/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. Projděte si dokumentaci k navrhovanému projektu a v případě potřeby výsledky upřesněte pomocí nových výzev.

7. Přesuňte navrženou dokumentaci k projektu do souboru dokumentace projektu.

   Například vytvořte soubor README.md v kořenovém adresáři pracovního prostoru a vložte do něj navrhovaný obsah.

   Pomocí režimu Zeptejte se agenta můžete navrhnout aktualizace pro konkrétní části projektu po vytvoření dokumentu nebo použít jiné nástroje GitHub Copilot, které vám pomůžou s aktualizacemi.

Použití režimu plánování ke generování dokumentace k projektu

Režim plánu je nejvhodnější pro vytvoření podrobného plánu implementace před generováním dokumentace k projektu. Režim Plán analyzuje základ kódu, identifikuje požadavky na dokumentaci a vytvoří podrobný plán. Jakmile je plán schválen, můžete ho předat do režimu agenta pro provedení.

Pomocí následujícího postupu vygenerujte dokumentaci k projektu, jako je například soubor README.md, pomocí režimu Plánu:

1. Identifikujte požadavky na dokumentaci a podpůrné prostředky.

2. Otevřete zobrazení chatu a spusťte novou relaci chatu pomocí režimu Plánování.

3. Zadejte výzvu, která popisuje úlohu dokumentace.

   Například: "Potřebuji vytvořit soubor README a podpůrnou dokumentaci pro tento projekt. Soubor README by měl zahrnovat: název projektu, popis, obsah, instalaci, použití, funkce, konfiguraci a licenci.

4. Zkontrolujte plán implementace.

   Po chvíli agent plánu vypíše plán v zobrazení Chat. Tento plán poskytuje souhrnný souhrn a rozpis kroků, včetně jakýchkoli otevřených otázek k objasnění. Několikrát můžete iterovat, abyste upřesnili požadavky, upravili rozsah nebo odpověděli na otázky.

5. Po dokončení plánu vyberte Spustit implementaci a předejte plán do režimu agenta. Pokud chcete plán uložit jako soubor Markdownu pro pozdější použití, vyberte Otevřít v Editoru .

   Když vyberete Start Implementation, GitHub Copilot přepne do režimu agenta a začne implementovat dokumentaci na základě schváleného plánu. Zkontrolujte vygenerované soubory dokumentace a přijměte nebo zahoďte změny.

Použití režimu agenta ke generování dokumentace k projektu

Režim agenta je nejvhodnější pro generování dokumentace k projektu, která vyžaduje podrobné porozumění projektu. Režim agenta analyzuje celou strukturu projektu předtím, než vygeneruje dokumentaci k projektu. Když shromáždíte informace z více souborů a složek, režim agenta může popisovat složité vztahy a zahrnovat propojení mezi dokumenty.

Pomocí následujícího postupu vygenerujte dokumentaci k projektu, jako je například soubor README.md, pomocí režimu agenta:

1. Identifikujte požadavky na dokumentaci a podpůrné prostředky.

2. Otevřete zobrazení chatu a spusťte novou relaci chatu pomocí režimu agenta.

3. Přidejte do chatovací relace kontext.

   Účastníci chatu nejsou v režimu agenta k dispozici, takže v rámci výzvy nemůžete zadat @terminal . Do chatové relace ale můžete přidat kontext pomocí #codebase a přidáním souborů a složek pracovního prostoru do kontextu chatu. Externí soubory je možné otevřít v Visual Studio Code a pak přidat do kontextu chatu pomocí tlačítka Attach Context.

4. Zadejte výzvu k vytvoření požadované dokumentace k projektu.

   Příklad: "Vygenerujte kolekci souborů dokumentace projektu. Vytvořte nebo aktualizujte soubor README.md pracovního prostoru pro toto úložiště. Vytvořte nebo aktualizujte soubor UsageExamples.md. Vytvořte nebo aktualizujte soubor ChangeLog.md. Zahrňte propojení mezi soubory dokumentace, prolinkujte třídy a metody a zajistěte konzistenci napříč dokumenty.

5. Zkontrolujte soubory dokumentu a pak aktualizace uložte nebo zahoďte.

   Aktualizujte soubor pomocí výzev ke korekci nebo vylepšení konkrétních sekcí, pokud je to nezbytné.

Možnosti režimu agenta

Existuje několik úloh dokumentace, kdy je nejlepší volbou režim agenta.

1. Generování dokumentace pro více souborů a mezi soubory

   • Režim agenta může analyzovat celou strukturu projektu, shromažďovat informace z více souborů a složek a generovat dokumentaci, která propojuje a shrnuje obsah v rámci základu kódu. Například generování kompletního odkazu na rozhraní API nebo souboru README, který popisuje všechny hlavní komponenty.

2. Automatizovaná analýza a shrnutí projektů

   • Režim agenta může provádět úlohy, jako je shrnutí architektury, identifikace hlavních tříd/služeb a vytváření diagramů nebo tabulek, které vyžadují porozumění relacím mezi soubory a komponentami.

3. Generování dynamického obsahu (například příklady použití, tabulky tříd)

   • Režim agenta může prohledat projekt a vygenerovat příklady použití, tabulky odpovědnosti tříd nebo seznamy veřejných rozhraní API.

4. Dávkové zpracování dokumentačních úloh

   • Režim agenta může spustit posloupnost úloh dokumentace (například aktualizovat soubor README, vytvořit CONTRIBUTING.md, vygenerovat dokumentaci k rozhraní API, aktualizovat protokol změn) v jednom pracovním postupu.

5. Inteligentní propojení a navigace

   • Režim agenta může vytvářet propojení mezi soubory dokumentace, propojovat třídy a metody a zajistit konzistenci napříč dokumentací.

Režim agenta je ideální pro úlohy dokumentace s podporou celého projektu, více souborů a kontextových úloh, které vyžadují analýzu, syntézu a koordinaci.

Shrnutí

GitHub Copilot vám může pomoct vygenerovat dokumentaci k projektu, která splňuje konkrétní potřeby projektu a jejích zúčastněných stran. Zobrazení chatu se dá použít ke generování dokumentace k projektu ve třech různých režimech: Zeptejte se, Agent a Plán. Každý režim má své vlastní silné a slabé stránky a nejlepší režim, který se má použít, závisí na konkrétním úkolu. Režim Zeptejte se agenta je nejvhodnější pro kladení otázek ohledně základu kódu nebo technologických konceptů. Režim Agent je nejvhodnější pro generování dokumentace k projektu, která vyžaduje podrobné porozumění projektu. Režim Plán je nejvhodnější pro vytvoření podrobného plánu implementace před generováním dokumentace, která se pak dá předat do režimu agenta pro spuštění.