Generowanie dokumentacji projektu przy użyciu GitHub Copilot

Ukończone

W dokumentacji projektu opisano przeznaczenie, cele i wymagania projektu. Aby utworzyć dokumentację projektu, musisz zrozumieć strukturę projektu, jej składniki i sposób interakcji składników ze sobą.

widok czatu GitHub Copilot to idealne narzędzie do generowania dokumentacji projektu, ponieważ może analizować całą strukturę projektu i udostępniać ogólne omówienie projektu. Widok czatu może również służyć do generowania określonych typów dokumentacji, takich jak pliki README, dokumentacja interfejsu API i inne dokumenty związane z projektem.

Aby wygenerować dokumentację projektu, możesz użyć każdego z trybów widoku czatu (Zapytaj, agenta lub planu). Każdy tryb ma własne mocne i słabe strony. Specyfikacje projektu i inne ograniczenia wpływają na tryb, który powinien być używany.

Ważne

W przypadku korzystania z widoku czatu w trybie agenta każdy monit jest wliczany jako jedno żądanie Premium, pomnożony przez mnożnik modelu. GitHub Copilot może wykonać kilka kroków, aby ukończyć zadanie, ale te kroki nie są wliczane do Twojego zużycia premium. Opłaty są naliczane tylko za polecenia, które wprowadzasz. Łączna liczba użytych żądań premium zależy od liczby monitów wprowadzonych i wybranego modelu.

Ustanawianie wymagań dotyczących dokumentacji projektu

Typy dokumentacji i wymagania dotyczące zawartości zależą od projektu, zamierzonych odbiorców i standardów przyjętych przez organizację.

Na przykład README.md mogą zawierać następujące sekcje:

• Tytuł projektu: nazwa projektu.
• Opis: krótki przegląd tego, co robi projekt i dlaczego istnieje.
• Spis treści: opcjonalny, ale przydatny w przypadku dłuższych plików README.
• Instalacja: instrukcje dotyczące sposobu instalowania i konfigurowania projektu.
• Użycie: przykłady użycia projektu, w tym fragmenty kodu lub zrzuty ekranu.
• Funkcje: lista kluczowych cech lub funkcjonalności.
• Konfiguracja: szczegółowe informacje na temat wszystkich opcji konfiguracji lub zmiennych środowiskowych.
• Wskazówki dotyczące wnoszenia wkładu do projektu.
• Licencja: wszelkie licencje używane przez projekt rozproszony.
• Podziękowania i uznania: uznanie współautorów, bibliotek lub używanych zasobów.
• Kontakt: Jak skontaktować się z osobami odpowiedzialnymi za projekt lub zespół projektowy.
• Dziennik zmian: historia zmian i aktualizacji (czasami połączona z oddzielnym plikiem).

GitHub Copilot Chat może pomóc w wygenerowaniu dokumentacji projektu, która spełnia określone potrzeby projektu i jego uczestników projektu.

Generowanie dokumentacji projektu przy użyciu trybu zapytaj agenta

Tryb zapytaj agenta może służyć do analizowania obszaru roboczego, a następnie generowania dokumentacji.

Użyj następującego procesu, aby wygenerować dokumentację projektu przy użyciu trybu Zapytaj agenta:

1. Zidentyfikuj wymagania dotyczące dokumentacji i zasoby pomocnicze.

   • Zidentyfikuj wymagania dotyczące dokumentacji projektu. Identyfikowanie typów dokumentacji i wymaganych sekcji dokumentów.

   • Zidentyfikuj zasoby wymagane do wygenerowania dokumentacji. Obszar roboczy kodu może być jedynym wymaganym zasobem. Może jednak być konieczne dodanie kontekstu do czatu w sekcjach takich jak "Udział", "Podziękowania" i "Kontakt".

2. Otwórz widok Czat i rozpocznij nową sesję czatu przy użyciu trybu Zapytaj agenta.

3. Dodaj kontekst do sesji czatu.

   • Kontekst można dodać do sesji czatu, przeciągając i upuszczając pliki z widoku EKSPLORATORa Visual Studio Code do widoku czatu. Możesz również użyć przycisku Dołącz kontekst (ikona papieru).
   • Możesz otworzyć pliki zewnętrzne w edytorze kodu, aby uwzględnić zasoby, które nie są częścią obszaru roboczego, i użyć ich do zapewnienia większego kontekstu. Możesz na przykład otworzyć pliki markdown zawierające wytyczne współautora lub informacje kontaktowe, a następnie użyć przycisku Dołącz kontekst , aby dodać je do kontekstu widoku czatu.

4. Wprowadź serię monitów, które badają wymagania dotyczące dokumentacji.

   Możesz użyć trybu Zapytaj agenta, aby przeanalizować obszar roboczy i utworzyć historię sesji czatu, która obsługuje wymagania dotyczące dokumentacji. Opisywanie celów może pomóc w ustaleniu kontekstu sesji czatu. Zadawanie pytań, które spełniają Twoje wymagania, pomaga GitHub Copilot zidentyfikowaniu informacji potrzebnych do wygenerowania dokumentacji.

   Odśwież dodany kontekst zgodnie z potrzebami.

5. Wprowadź monit z prośbą o sugerowaną dokumentację projektu z listą wymaganych sekcji, które zostały zidentyfikowane w pierwszym kroku.

   Na przykład: "#codebase /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. Przejrzyj sugerowaną dokumentację projektu i uściślij wyniki, korzystając z nowych monitów, jeśli to konieczne.

7. Przenieś sugerowaną dokumentację projektu do pliku dokumentacji projektu.

   Na przykład utwórz plik README.md w katalogu głównym obszaru roboczego i wstaw sugerowaną zawartość do pliku.

   Możesz użyć trybu Zapytaj agenta, aby zasugerować aktualizacje dla określonych sekcji projektu po utworzeniu dokumentu lub użyć innych narzędzi GitHub Copilot, aby ułatwić aktualizowanie.

Używanie trybu planu do generowania dokumentacji projektu

Tryb planu najlepiej nadaje się do tworzenia szczegółowego planu implementacji przed wygenerowaniem dokumentacji projektu. Tryb planu analizuje bazę kodu, identyfikuje wymagania dotyczące dokumentacji i tworzy plan krok po kroku. Po zatwierdzeniu planu można przekazać go do trybu agenta w celu wykonania.

Użyj następującego procesu, aby wygenerować dokumentację projektu, taką jak plik README.md, przy użyciu trybu planu:

1. Zidentyfikuj wymagania dotyczące dokumentacji i zasoby pomocnicze.

2. Otwórz widok Czat i rozpocznij nową sesję czatu przy użyciu trybu Planu.

3. Wprowadź monit opisujący zadanie dokumentacji.

   Na przykład: "Muszę utworzyć plik README i dokumentację pomocniczą dla tego projektu. Plik README powinien zawierać: Tytuł projektu, Opis, Spis treści, Instalacja, Użycie, Funkcje, Konfiguracja i Licencja.

4. Zapoznaj się z planem implementacji.

   Po kilku chwilach agent planu wyświetli plan w widoku czatu. Plan zawiera wysokopoziomowe podsumowanie i podział kroków, w tym wszelkie otwarte pytania do wyjaśnienia. Można iterować wiele razy, aby wyjaśnić wymagania, dostosować zakres lub odpowiedzieć na pytania.

5. Po zakończeniu planu wybierz pozycję Rozpocznij implementację , aby przekazać plan do trybu agenta, lub wybierz pozycję Otwórz w edytorze , aby zapisać plan jako plik Markdown do późniejszego użycia.

   Po wybraniu Start Implementation GitHub Copilot przełącza się do trybu agenta i rozpoczyna wdrażanie dokumentacji opartej na zatwierdzonym planie. Przejrzyj wygenerowane pliki dokumentacji i zaakceptuj lub odrzuć zmiany.

Generowanie dokumentacji projektu przy użyciu trybu agenta

Tryb agenta najlepiej nadaje się do generowania dokumentacji projektu, która wymaga dogłębnego zrozumienia projektu. Tryb agenta analizuje całą strukturę projektu przed wygenerowaniem dokumentacji projektu. Zbierając informacje z wielu plików i folderów, tryb agenta może opisywać złożone relacje i dołączać łącza między dokumentami.

Użyj następującego procesu, aby wygenerować dokumentację projektu, taką jak plik README.md, przy użyciu trybu agenta:

1. Zidentyfikuj wymagania dotyczące dokumentacji i zasoby pomocnicze.

2. Otwórz widok Czat i rozpocznij nową sesję czatu przy użyciu trybu agenta.

3. Dodaj kontekst do sesji czatu.

   Uczestnicy czatu nie są dostępni w trybie agenta, więc nie można określić @terminal jako części podpowiedzi. Można jednak dodać kontekst do sesji czatu, używając #codebase oraz dodając pliki i foldery obszaru roboczego do kontekstu czatu. Pliki zewnętrzne można otwierać w Visual Studio Code, a następnie dodawać do kontekstu czatu przy użyciu przycisku Attach Context.

4. Wprowadź monit o utworzenie zamierzonej dokumentacji projektu.

   Na przykład: "Generuj kolekcję plików dokumentacji projektu. Utwórz lub zaktualizuj plik README.md obszaru roboczego dla tego repozytorium. Utwórz lub zaktualizuj plik UsageExamples.md. Utwórz lub zaktualizuj plik ChangeLog.md. Dołącz łącza między plikami dokumentacji, klasami i metodami odwołania krzyżowego oraz zapewnij spójność w dokumentach.

5. Przejrzyj pliki dokumentów, a następnie zapisz lub odrzuć aktualizacje.

   Zaktualizuj plik przy użyciu monitów, aby poprawić lub ulepszyć określone sekcje w razie potrzeby.

Możliwości trybu agenta

Istnieje kilka zadań dokumentacji, w których tryb agenta jest najlepszym wyborem.

1. Generowanie dokumentacji obejmującej wiele plików oraz między nimi.

   • Tryb agenta może analizować całą strukturę projektu, zbierać informacje z wielu plików i folderów oraz generować dokumentację, która łączy i podsumowuje zawartość w bazie kodu. Na przykład wygenerowanie pełnej dokumentacji interfejsu API lub pliku README opisującego wszystkie główne składniki.

2. Automatyczna analiza i podsumowywanie projektów.

   • Tryb agenta może wykonywać zadania, takie jak podsumowywanie architektury, identyfikowanie głównych klas/usług oraz tworzenie diagramów lub tabel wymagających zrozumienia relacji między plikami i składnikami.

3. Generowanie zawartości dynamicznej (na przykład przykłady użycia, tabele klas)

   • Tryb agenta umożliwia skanowanie projektu w celu wygenerowania przykładów użycia, tabel odpowiedzialności klas lub list publicznych interfejsów API.

4. Zadania dokumentacji Batch.

   • Tryb agenta może wykonywać sekwencję zadań dokumentacyjnych (na przykład zaktualizować plik README, utworzyć CONTRIBUTING.md, wygenerować dokumentację interfejsu API, zaktualizować dziennik zmian) w ramach jednego przepływu pracy.

5. Inteligentne łączenie i nawigacja.

   • Tryb agenta może tworzyć powiązania między plikami dokumentacji, odwoływać się do klas i metod oraz zapewniać spójność w dokumentach.

Tryb agenta jest idealny dla zadań dokumentacji obejmujących cały projekt, wiele plików i kontekstowych, które wymagają analizy, syntezy i koordynacji.

Podsumowanie

GitHub Copilot może pomóc w wygenerowaniu dokumentacji projektu, która spełnia określone potrzeby projektu i jego uczestników projektu. Widok czatu może służyć do generowania dokumentacji projektu w trzech różnych trybach: Zapytanie, Agent i Plan. Każdy tryb ma własne mocne i słabe strony, a najlepszy tryb do użycia zależy od konkretnego zadania. Tryb agenta Pytaj jest najlepszy do zadawania pytań dotyczących bazy kodu lub koncepcji technologicznych. Tryb agenta najlepiej nadaje się do generowania dokumentacji projektu, która wymaga dogłębnego zrozumienia projektu. Tryb Planowania najlepiej nadaje się do tworzenia szczegółowego planu implementacji przed wygenerowaniem dokumentacji, która następnie może zostać przekazana do trybu Agenta w celu wykonania.