Генеруйте документацію проєкту за допомогою GitHub Copilot

  • 6 хв.

У документації проекту описано призначення, цілі та вимоги проекту. Щоб створити документацію проекту, потрібно зрозуміти структуру проекту, його компоненти та спосіб взаємодії компонентів між собою.

Чат-режим GitHub Copilot є ідеальним інструментом для створення документації проєкту, оскільки він може аналізувати всю структуру проєкту та надавати загальний огляд проєкту. Подання чату також можна використовувати для створення документів певного типу, наприклад файлів README, посилань на API та інших документів, пов'язаних із проектом.

Ви можете використовувати кожен із режимів перегляду чату (Запитати, Агент або Планувати) для створення документації проєкту. Кожен режим має свої сильні та слабкі сторони. Специфікації проекту та інші обмеження впливають на режим, який слід використовувати.

Важливо

Коли ви використовуєте перегляд чату в режимі агента, кожен вводний запит рахується як один преміум-запит, помножений на множник моделі. GitHub Copilot може знадобитися кілька наступних дій для виконання завдання, але ці дії не враховуються у використанні вашого преміум-запиту. Виставляються лише ті підказки, які ви вводите. Загальна кількість запитів на премію залежить від кількості запитів, які ви введете, і обраної моделі.

Установлення вимог до документації проекту

Типи документації та вимоги до вмісту залежать від проекту, цільових споживачів і стандартів, прийнятих організацією.

Наприклад, README.md може містити такі розділи:

  • Назва проекту: назва проекту.
  • Опис: короткий огляд того, що робить проект і чому він існує.
  • Зміст: необов'язковий, але корисний для довших READMEs.
  • Інсталяція: інструкції з інсталяції та настроювання проекту.
  • Використання. Приклади використання проекту, зокрема фрагменти коду або знімки екрана.
  • Функції: Список основних функцій або функцій.
  • Конфігурація: відомості про будь-які параметри конфігурації або змінні середовища.
  • Внесок: Рекомендації щодо внеску у проект.
  • Ліцензія. Будь-які ліцензії, які використовуються в розподіленому проекті.
  • Кредити та підтвердження: розпізнавання співавторів, бібліотек або ресурсів, що використовуються.
  • Контактна особа: Як зв'язатися з супроводжувачами або командою проекту.
  • Журнал змін і оновлень (іноді пов'язаний з окремим файлом).

GitHub Copilot Chat допоможе вам створити документацію проєкту, яка відповідає конкретним потребам вашого проєкту та його зацікавлених сторін.

Використовуйте режим Ask agent для генерації документації проєкту

Режим Ask агента можна використовувати для аналізу робочого простору та подальшої генерації документації.

Використовуйте наступний процес для генерації документації проєкту в режимі агента запиту:

  1. Визначте вимоги до документації та допоміжні ресурси.

    • Визначте вимоги до документації для проекту. Визначте типи документації та необхідні розділи документів.

    • Визначте ресурси, необхідні для створення документації. Робоча область коду може бути єдиним обов'язковим ресурсом. Однак може знадобитися додати контекст до чату для таких розділів, як "Внесок", "Кредити" та "Контакт".

  2. Відкрийте перегляд чату і почніть нову сесію чату в режимі агента запитати.

  3. Додавання контексту до сеансу чату.

    • Ви можете додати контекст до чату, перетягуючи файли з огляду провідника Visual Studio Code у перегляд чату. Ви також можете скористатися кнопкою Прикріпити контекст (іконка скріпки).
    • Ви можете відкрити зовнішні файли в редакторі коду, щоб включити ресурси, які не входять до робочої області, і використовувати їх, щоб надати більше контексту. Наприклад, ви можете відкрити файли markdown, які містять правила для учасників або контактну інформацію, а потім за допомогою кнопки Прикріпити контекст додати їх до контексту перегляду чату.

  4. Введіть ряд запитів, які досліджують вимоги до документації.

    Ви можете використовувати режим Ask agent для аналізу робочого простору та створення історії чат-сесій, яка підтримує ваші вимоги до документації. Опис ваших цілей може допомогти встановити контекст для сеансу чату. Запитання, що відповідають вашим вимогам, допомагає GitHub Copilot визначити інформацію, необхідну для створення документації.

    За потреби оновіть доданий контекст.

  5. Введіть запит із запитом на документацію проекту із запитом на введення необхідних розділів, визначених на першому кроці.

    Наприклад: «#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. Перегляньте запропоновану документацію проекту та уточніть результати за потреби, використовуючи нові підказки.

  7. Перемістіть запропоновану документацію проекту до файлу документації проекту.

    Наприклад, створіть файл README.md в кореневій частині робочої області та вставте рекомендований вміст у файл.

    Ви можете використовувати режим Ask agent, щоб пропонувати оновлення для певних розділів вашого проєкту після створення документа, або використовувати інші GitHub Copilot інструменти для допомоги з оновленнями.

Використовуйте режим плану для створення документації проєкту

Режим планування найкраще підходить для створення детального плану реалізації перед формуванням документації проєкту. Режим плану аналізує кодову базу, визначає вимоги до документації та створює покроковий план. Після затвердження плану ви можете передати його в режим агента для виконання.

Використовуйте наступний процес для створення документації проєкту, наприклад README.md-файл, у режимі планування:

  1. Визначте вимоги до документації та допоміжні ресурси.

  2. Відкрийте перегляд чату та почніть нову сесію чату в режимі планування.

  3. Введіть запит, який описує ваше завдання з документації.

    Наприклад: «Мені потрібно створити файл README та супровідну документацію для цього проєкту. README має включати: назву проєкту, опис, зміст, встановлення, використання, функції, конфігурацію та ліцензію.»

  4. Перегляньте план впровадження.

    Через кілька хвилин агент плану виводить план у вигляді чату. План містить загальний огляд і розподіл кроків, включаючи відкриті питання для уточнення. Ви можете ітерувати кілька разів, щоб уточнити вимоги, скоригувати обсяг або відповісти на запитання.

  5. Після завершення плану виберіть Start Implementation , щоб передати план у режим агента, або виберіть Open in Editor , щоб зберегти план як файл Markdown для подальшого використання.

    Коли ви обираєте Start Implementation, GitHub Copilot переходить у режим агента і починає впроваджувати документацію на основі затвердженого плану. Перегляньте згенеровані документаційні файли та прийміть або відхиліть зміни.

Створення документації проекту за допомогою режиму агента

Режим агента найкраще підходить для створення документації проекту, яка потребує поглибленого розуміння проекту. Режим агента аналізує всю структуру проекту, перш ніж вона створить документацію проекту. Збираючи інформацію з кількох файлів і папок, режим агента може описувати складні зв'язки та включати зв'язки між документами.

Використовуйте наступний процес для генерації документації проєкту, наприклад README.md файлу, у режимі агента:

  1. Визначте вимоги до документації та допоміжні ресурси.

  2. Відкрийте подання чату та розпочніть новий сеанс чату за допомогою режиму агента.

  3. Додавання контексту до сеансу чату.

    Учасники чату недоступні в режимі агента, тому не можна вказати @terminal як частину запиту. Однак можна додати контекст до сеансу чату, використовуючи #codebase та додавши файли й папки робочої області до контексту чату. Зовнішні файли можна відкрити у Visual Studio Code, а потім додати до контексту чату за допомогою кнопки Attach Context.

  4. Введіть запит, щоб створити документацію проекту.

    Наприклад: "Створення колекції файлів документації проекту. Створіть або оновіть файл README.md робочої області для цього сховища. Створіть або оновіть файл UsageExamples.md. Створіть або оновіть файл ChangeLog.md. Додайте зв'язки між файлами документації, класами та методами перехресного посилання та забезпечте узгодженість документів".

  5. Перегляньте файли документа, а потім збережіть або скасуйте оновлення.

    Оновіть файл, використовуючи підказки, щоб виправити або покращити певні розділи, якщо необхідно.

Можливості режиму агента

Є кілька завдань документації, де найкращим вибором є режим агента.

  1. Створення багатофайлної та перехресної документації.

    • Режим агента може аналізувати всю структуру проекту, збирати інформацію з кількох файлів і папок і створювати документацію, яка зв'язує та підсумовує вміст у всій базі коду. Наприклад, створення повного довідника API або README, який описує всі основні компоненти.

  2. Автоматичний аналіз і зведення проектів.

    • Режим агента може виконувати такі завдання, як зведення архітектури, визначення основних класів або служб, а також створення схем або таблиць, які вимагають розуміння зв'язків між файлами та компонентами.

  3. Динамічне створення вмісту (наприклад, приклади використання, таблиці класів)

    • Режим агента може сканувати проект, щоб створити приклади використання, таблиці відповідальності за клас або списки загальнодоступних API.

  4. Завдання пакетної документації.

    • Режим агента може виконувати послідовність завдань документації (наприклад, оновлювати README, створювати CONTRIBUTING.md, створювати документи API, журнал змін) в одному робочому циклі.

  5. Інтелектуальне зв'язування та навігація.

    • Режим агента може створювати зв'язки між файлами документації, класами та методами перехресного посилання, а також забезпечувати узгодженість документів.

Режим агента ідеально підходить для завдань із документацією на рівні проекту, багатофайлів і контексту, які потребують аналізу, синтезу та координації.

Зведення

GitHub Copilot може допомогти вам створити документацію проєкту, яка відповідає конкретним потребам вашого проєкту та його зацікавлених сторін. Перегляд чату можна використовувати для генерації документації проєкту у трьох різних режимах: Запитати, Агент і Планувати. Кожен режим має свої сильні та слабкі сторони, а найкращий режим залежить від певного завдання. Режим Ask агента найкраще підходить для запитань про вашу кодову базу або технологічні концепції. Режим агента найкраще підходить для створення документації проєкту, яка вимагає глибокого розуміння проєкту. Режим Plan найкраще підходить для створення детального плану впровадження перед генерацією документації, яку потім можна передати в режим агента для виконання.