使用 GitHub Copilot 生成项目文档

  • 6 分钟

项目文档描述了项目的用途、目标和要求。 若要创建项目文档，需要了解项目结构、其组件以及组件相互交互的方式。

GitHub Copilot的聊天视图是生成项目文档的理想工具，因为它可以分析整个项目结构并提供项目的概要概述。 聊天视图还可用于生成特定类型的文档，例如自述文件、API 引用和其他与项目相关的文档。

可以使用每个聊天视图模式（询问、代理或计划）生成项目文档。 每个模式都有自己的长处和弱点。 项目规范和其他约束会影响应使用哪种模式。

重要

在代理模式下使用聊天视图时，输入的每个提示都算作一个高级请求，乘以模型的乘数。 GitHub Copilot可能会采取多个后续作来完成任务，但这些后续作不计入高级请求使用情况。 仅对你输入的提示进行计费。 使用的高级请求总数取决于你输入的提示数和选择的模型。

制定项目文档要求

文档类型和内容要求取决于项目、预期使用者以及组织采用的标准。

例如，README.md 可以包含以下部分：

  • 项目标题：项目的名称。
  • 说明：简要概述项目的作用及其存在原因。
  • 目录：可选，但对较长的 README 有帮助。
  • 安装：有关如何安装和设置项目的说明。
  • 用法：如何使用项目的示例，包括代码片段或屏幕截图。
  • 功能：关键特征或功能的列表。
  • 配置：有关任何配置选项或环境变量的详细信息。
  • 参与：参与项目的指南。
  • 许可证：分布式项目使用的任何许可证。
  • 额度和确认：识别参与者、库或使用的资源。
  • 联系人：如何联系维护人员或项目团队。
  • 更改日志：更改和更新的历史记录（有时链接到单独的文件）。

GitHub Copilot聊天可以帮助你生成满足项目及其利益干系人的特定需求的项目文档。

使用 Ask 代理模式生成项目文档

Ask 代理模式可用于分析工作区，然后生成文档。

使用以下过程使用 Ask 代理模式生成项目文档：

  1. 确定文档要求和支持资源。

    • 确定项目的文档要求。 确定文档的类型和所需的文档部分。

    • 确定生成文档所需的资源。 代码工作区可能是唯一必需的资源。 但是，您可能需要为“参与”、“致谢”和“联系人”等部分在聊天中添加上下文。

  2. 打开聊天视图，并使用 Ask 代理模式启动新的聊天会话。

  3. 将上下文添加到聊天会话。

    • 可以通过将Visual Studio Code的 EXPLORER 视图中的文件拖放到聊天视图中，将上下文添加到聊天会话。 还可以使用 “附加上下文 ”按钮（剪纸图标）。
    • 可以在代码编辑器中打开外部文件，以包含不属于工作区的资源，并使用它们来提供更多上下文。 例如，可以打开包含参与者指南或联系信息的 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. 输入一个提示命令，描述文档任务。

    例如：“我需要为此项目创建自述文件和支持文档。 自述文件应包括：项目标题、说明、目录、安装、使用情况、功能、配置和许可证。

  4. 查看实施计划。

    片刻之后，计划代理在“聊天”视图中输出计划。 该计划提供了一个概要摘要和步骤明细，包括任何待澄清的公开问题。 可以多次迭代，来阐明要求、调整项目范围或回答问题。

  5. 完成计划后，选择 “开始实现 ”以将计划移交给代理模式，或选择“ 在编辑器中打开 ”以将计划保存为 Markdown 文件以供以后使用。

    选择“启动实现时，GitHub Copilot切换到代理模式，并开始根据批准的计划实现文档。 查看生成的文档文件并接受或放弃更改。

使用代理模式生成项目文档

代理模式最适合生成需要深入了解项目的项目文档。 代理模式在生成项目文档之前分析整个项目结构。 通过从多个文件和文件夹收集信息，代理模式可以描述复杂的关系，并包括文档之间的链接。

使用以下过程通过代理模式生成项目文档，例如 README.md 文件：

  1. 确定文档要求和支持资源。

  2. 打开聊天视图，并使用代理模式启动新的聊天会话。

  3. 将上下文添加到聊天会话。

    聊天参与者在代理模式下不可用，因此无法指定 @workspace 为提示的一部分。 但是，您可以使用#codebase 来为聊天会话添加上下文，并通过将工作区文件和文件夹添加到聊天上下文中来增强聊天内容。 可以在Visual Studio Code中打开外部文件，然后使用 Attach Context 按钮添加到聊天上下文中。

  4. 输入提示以创建预期的项目文档。

    例如：“生成项目文档文件的集合。 为此存储库创建或更新工作区 README.md 文件。 创建或更新 UsageExamples.md 文件。 创建或更新 ChangeLog.md 文件。 包括文档文件、跨引用类和方法之间的链接，并确保文档的一致性。

  5. 查看文档文件，然后保存或放弃更新。

    如有必要，请使用提示更新文件以更正或增强特定节。

代理模式功能

有几项文档任务适合使用代理模式。

  1. 多文件和跨文件文档生成。

    • 代理模式可以分析整个项目结构，从多个文件和文件夹收集信息，并生成链接和汇总代码库内容的文档。 例如，生成描述所有主要组件的完整 API 引用或自述文件。

  2. 自动化项目分析和汇总。

    • 代理模式可以执行汇总体系结构、标识主类/服务以及生成需要了解文件和组件之间的关系的关系图或表等任务。

  3. 动态内容生成（例如使用情况示例、类表）

    • 代理模式可以扫描项目以生成使用示例、类责任表或公共 API 列表。

  4. Batch 文档任务。

    • 代理模式可以在一个工作流中执行一系列文档任务（例如，更新自述文件、创建 CONTRIBUTING.md、生成 API 文档、更新更改日志）。

  5. 智能链接和导航。

    • 代理模式可以在文档文件、跨引用类和方法之间创建链接，并确保文档之间的一致性。

代理模式非常适合需要分析、合成和协调的项目范围、多文件和上下文感知文档任务。

概要

GitHub Copilot可帮助你生成满足项目及其利益干系人的特定需求的项目文档。 聊天视图可用于以三种不同的模式生成项目文档：Ask、Agent 和 Plan。 每个模式都有自己的优缺点，使用的最佳模式取决于手头的特定任务。 Ask 代理模式最适合询问有关代码库或技术概念的问题。 代理模式最适合生成需要深入了解项目的项目文档。 计划模式最适合在生成文档之前创建详细的实施计划，然后可以将其移交给代理模式以供执行。