Создание документации по проекту с помощью GitHub Copilot

  • 6 мин

Документация по проекту описывает назначение, цели и требования проекта. Чтобы создать документацию по проекту, необходимо понять структуру проекта, ее компоненты и взаимодействие компонентов друг с другом.

представление чата GitHub Copilot идеально подходит для создания документации по проекту, так как она может анализировать всю структуру проекта и предоставлять общие сведения о проекте. Представление чата также можно использовать для создания определенных типов документации, таких как файлы README, ссылки НА API и другие документы, связанные с проектом.

Для создания документации по проекту можно использовать каждый из режимов представления чата (Ask, Agent или Plan). Каждый режим имеет свои собственные сильные и слабые стороны. Спецификации проекта и другие ограничения влияют на то, какой режим следует использовать.

Это важно

При использовании чата в режиме агента каждый вводимый вами запрос засчитывается как один премиум-запрос, умноженный на коэффициент модели. GitHub Copilot может предпринять несколько дальнейших действий для выполнения задачи, но эти действия не учитываются при использовании запросов премиум. Оплачиваются только вводимые запросы. Общее количество используемых запросов уровня "Премиум" зависит от количества запросов, которые вы вводите, и выбранной модели.

Установка требований к документации по проекту

Типы документации и требования к содержимому зависят от проекта, предполагаемых потребителей и стандартов, принятых организацией.

Например, README.md могут включать следующие разделы:

  • Название проекта: имя проекта.
  • Описание. Краткий обзор того, что делает проект и почему он существует.
  • Оглавление: необязательно, но полезно для длинных файлов README.
  • Установка. Инструкции по установке и настройке проекта.
  • Использование: примеры использования проекта, включая фрагменты кода или снимки экрана.
  • Функции: список ключевых особенностей или функционала.
  • Конфигурация: сведения о любых параметрах конфигурации или переменных среды.
  • Участие: рекомендации по участию в проекте.
  • Лицензия: все лицензии, используемые распределенным проектом.
  • Благодарности и признание: Признание участников, библиотек или используемых ресурсов.
  • Контакт. Как связаться с обслуживателями или командой проектов.
  • Журнал изменений: журнал изменений и обновлений (иногда связан с отдельным файлом).

GitHub Copilot Чат поможет вам создать документацию по проекту, которая соответствует конкретным потребностям проекта и заинтересованным лицам.

Создание документации по проекту с помощью режима агента Ask

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

Используйте следующий процесс для создания документации по проекту с помощью режима агента Ask:

  1. Определите требования к документации и вспомогательные ресурсы.

    • Определите требования к документации для проекта. Определите типы документации и необходимые разделы документов.

    • Определите ресурсы, необходимые для создания документации. Рабочая область кода может быть единственным необходимым ресурсом. Однако может потребоваться добавить контекст в чат для таких разделов, как "Участие", "Кредиты" и "Контакт".

  2. Откройте представление чата и запустите новый сеанс чата с помощью режима агента Ask.

  3. Добавьте контекст в сеанс чата.

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

  4. Введите ряд запросов, которые изучают требования к документации.

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

    При необходимости обновите добавленный контекст.

  5. Введите запрос, запрашивающий рекомендуемую документацию по проекту, в котором перечислены необходимые разделы, которые вы определили на первом шаге.

    Например: "@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. Просмотрите предлагаемую документацию по проекту и уточните результаты с помощью новых запросов, если это необходимо.

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

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

    Вы можете использовать режим агента Ask, чтобы предложить обновления для определенных разделов проекта после создания документа или использовать другие средства GitHub Copilot для поддержки обновлений.

Создание документации по проекту с помощью режима плана

Режим плана лучше всего подходит для создания подробного плана реализации перед созданием документации по проекту. Режим плана анализирует базу кода, определяет требования к документации и создает пошаговый план. После утверждения плана его можно передать в режим агента для выполнения.

Используйте следующий процесс для создания документации по проекту, например файла README.md, с помощью режима плана:

  1. Определите требования к документации и вспомогательные ресурсы.

  2. Откройте представление чата и запустите новый сеанс чата с помощью режима плана.

  3. Введите запрос, описывающий задачу документации.

    Например: "Мне нужно создать файл README и сопроводительную документацию для этого проекта. ReadME должен включать в себя: название проекта, описание, оглавление, установка, использование, компоненты, конфигурация и лицензия".

  4. Просмотрите план реализации.

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

  5. После завершения плана выберите "Запустить реализацию" , чтобы передать план в режим агента или нажмите кнопку "Открыть в редакторе ", чтобы сохранить план в виде файла Markdown для последующего использования.

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

Создание документации по проекту с помощью режима агента

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

Используйте следующий процесс для создания документации по проекту, например файла README.md, с помощью режима агента:

  1. Определите требования к документации и вспомогательные ресурсы.

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

  3. Добавьте контекст в сеанс чата.

    Участники чата недоступны в режиме агента, поэтому вы не можете указать @workspace в качестве части запроса. Однако можно добавить контекст в сеанс чата с помощью #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, Agent и Plan. Каждый режим имеет свои собственные сильные и слабые стороны, и лучший режим использования зависит от конкретной задачи. Режим "Ask agent" лучше всего подходит для задавания вопросов о кодовой базе и концепциях технологий. Режим агента лучше всего подходит для создания документации по проекту, требующей глубокого понимания проекта. Режим плана лучше всего подходит для создания подробного плана реализации перед созданием документации, которая затем может быть передана в режим агента для выполнения.