DeepDocs
访问网站
扫码查看
复制链接

自动与代码同步更新的AI文档工具

标签：AI文档 , API文档 , GitHub , README , 技术文档 , 持续文档 , 自动更新

DeepDocs

AI工作效率 / 编程/开发162 次浏览

综合介绍

DeepDocs是一个专为开发人员设计的AI工具，它能自动维护技术文档，确保文档内容与代码库的最新变更保持同步。这个工具以内置在GitHub的AI代理形式工作，它会持续监控代码提交。一旦发现代码发生变动，例如API接口或函数功能更新，DeepDocs就会自动扫描并更新相关的文档文件，包括README、API参考、SDK指南和教程等。

这个工具的核心在于实现了“持续文档”的理念，将文档更新这一繁琐的手工任务自动化。它的工作方式是，在代码变更被合并后，自动在新的分支中提出文档修改建议，并且会提供一份详细的报告，说明修改了什么以及为何修改。DeepDocs并非从零开始创建文档，而是专注于维护和更新现有的文档。它在更新时会保留原有的格式和行文风格，只对需要改动的部分进行智能编辑。这让开发团队可以将更多精力投入到功能开发上，而不必担心文档过时导致的问题。

功能列表

  • 持续文档更新: 在每次代码提交时，系统会自动扫描代码变更，并更新相关的文档部分，确保代码和文档永远保持一致。
  • 深度扫描 (Deep Scan): 用户可以随时手动触发全仓库扫描，一次性找出所有过时或缺失的文档内容，并进行修复。
  • 智能编辑: 在更新文档时，AI能够理解现有文档的结构和风格，只修改必要的部分，而不会重写整个文件，保留了原有的格式和语气。
  • 详细变更报告: 每次更新后，DeepDocs都会生成一份清晰的报告，详细列出具体的修改内容、修改原因以及触发本次更新的具体代码提交。
  • 原生GitHub集成: 工具完全集成在GitHub工作流中。它通过GitHub应用的形式安装，静默监听代码变动，并将文档更新放在独立的分支中进行，不会干扰到主代码库。
  • 隐私保护优先: 用户的代码不会被储存或建立索引。所有处理过程都是即时性的，不在外部存储任何数据，保证了代码的私密性。

使用帮助

DeepDocs的设计目标是让文档维护实现自动化，它的安装和使用流程非常简单，能直接融入到开发团队现有的GitHub工作流中。

安装与配置流程

整个设置过程只需要几分钟，分为以下三个步骤：

  1. 第一步：从GitHub市场安装应用
    • 访问 DeepDocs在GitHub Marketplace的页面。
    • 点击 “Install” 按钮，然后选择你希望为其安装此应用的GitHub账户或组织。
    • 接下来，你可以选择将DeepDocs授权给该账户下的“所有仓库” (All repositories) 还是“部分选定的仓库” (Only select repositories)。对于初次使用，建议先选择一个包含代码和相关文档的仓库进行尝试。
  2. 第二步：创建配置文件
    • 在你的仓库中，于根目录下创建一个名为 deepdocs.yml 的文件。这个文件是用来告诉DeepDocs需要监控哪些代码文件以及同步更新哪些文档文件的。
    • 打开 deepdocs.yml 文件，并定义代码源和文档目标。
    • 基础配置示例：假设你的项目结构如下： 
      /
├── src/
│   └── main.py
└── README.md

      你的 deepdocs.yml 文件内容可以这样写，来让README.md与src/目录下的代码保持同步：

      # deepdocs.yml
sync:
- source: /src/
target: /README.md
    • 高级配置示例（多个同步目标）：如果你的项目更复杂，比如同时拥有一个README.md和一份详细的docs/api_guide.md，并且分别对应不同的代码目录，你可以这样配置： 
      # deepdocs.yml
sync:
- source: /src/core/
target: /README.md
- source: /src/api/
target: /docs/api_guide.md
  3. 第三步：提交配置文件并触发首次扫描
    • 将你创建并编辑好的 deepdocs.yml 文件提交 (commit) 到你的仓库中。
    • 当你提交这个文件后，DeepDocs会立即被激活，并自动执行一次“深度扫描” (Deep Scan)。它会检查你所指定的source代码，并分析对应的target文档是否过时。
    • 扫描完成后，如果发现文档内容与当前代码不符，DeepDocs会自动创建一个新的分支（例如 deepdocs-update-20240921），并在这个分支里提交它对文档的修改。
    • 最后，它会向你的仓库发起一个拉取请求 (Pull Request)，你可以清晰地看到所有改动。你可以像审查团队成员的代码一样审查这些文档修改，确认无误后便可合并。

日常使用与核心功能操作

  • 自动更新 (Doc Update)完成初始配置后，你基本就不再需要手动操作了。每当你的团队向主分支提交新的代码时，DeepDocs都会在后台自动运行。它会分析这次提交所包含的代码变更，判断这些变更是否会影响到你在 deepdocs.yml 中定义的文档。如果有关联，它就会重复上述第三步的流程：创建新分支 -> 修改文档 -> 提起PR。这个过程是完全自动的，实现了“持续文档”的理念。
  • 手动深度扫描 (Deep Scan)除了自动触发，你也可以随时手动对整个仓库进行一次全面的文档检查。这个功能在以下几种情况中特别有用：
    1. 你刚刚完成一次大规模的代码重构。
    2. 你新添加了一个 deepdocs.yml 文件，想立即同步所有现有文档。
    3. 你不确定当前的文档是否完全准确，需要一次彻底的审查。要触发深度扫描，你只需要进入DeepDocs的控制台或相关界面，选择对应的仓库并点击“Deep Scan”按钮即可。

应用场景

  1. API文档维护对于提供API接口服务的项目，当后端工程师修改了某个接口的参数、返回值或行为后，通常需要手动去更新对应的API文档。使用DeepDocs，工程师只需提交代码，DeepDocs会自动检测到src/api/目录下的代码变更，并更新docs/api-reference.md文件中对应的接口描述，确保外部调用者看到的永远是最新信息。
  2. 开源项目快速上手指南开源项目的README.md是新用户的第一印象。当项目维护者添加了新功能或修改了启动命令后，DeepDocs可以自动更新README.md中的“快速开始”或“安装步骤”部分，避免新用户因为文档过时而遇到挫折，降低了项目的参与门槛。
  3. 内部SDK开发在一个大公司内部，一个团队开发的SDK可能会被多个其他团队使用。当SDK更新后，如果文档不及时，会造成内部沟通成本急剧增加。通过配置DeepDocs，SDK的开发团队可以确保每次发布新版SDK时，使用指南和函数库说明都能自动更新，保证了内部协作的顺畅。
  4. 代码示例与教程同步对于包含大量代码示例的教程文档，保持示例代码与实际可运行的代码一致非常关键。DeepDocs可以监控代码库中示例代码的变更，并自动将最新的代码片段同步更新到教程文章中，读者复制代码时不会因为版本问题而出错。

QA

  1. DeepDocs会从零开始帮我写文档吗？不会。DeepDocs的设计初衷是维护和更新已有的文档，而不是从空白开始创作。在项目初期，你还是需要先手动或使用其他AI工具（如GitHub Copilot）创建第一版文档。之后，DeepDocs会接管后续的同步和维护工作。
  2. 这个工具会把我的文档格式弄乱吗？不会。DeepDocs的一个核心特性是“智能更新”，它会分析并保留你现有的文档结构、格式和写作风格。它只会精准地修改需要更新的部分，比如一个函数签名或一个配置参数，而不会对整个文件进行重写。
  3. DeepDocs如何知道要更新哪部分文档？它通过 deepdocs.yml 配置文件中的 source 和 target 映射关系来确定关联。当你提交代码时，它会检查被修改的代码文件是否属于某个 source 路径，如果是，它就会去更新对应的 target 文档。其背后的AI模型能够理解代码变更的语义，并找到文档中对应的描述进行修改。
  4. 它和GitHub Copilot有什么区别？GitHub Copilot是一个代码辅助工具，可以在你编写代码或文档时提供建议，但它需要你手动触发或给出指令（prompt）。而DeepDocs是一个自动化工具，它在后台静默运行，无需人工干预。你可以把它看作是文档领域的CI/CD（持续集成/持续部署）工具，一旦设置好规则，它就会自动完成更新任务。
  5. 我的代码安全吗？根据官方说明，DeepDocs注重隐私和安全。它在处理你的代码时是即时性的（ephemerally），不会永久存储、缓存或索引你的任何代码，从而保障了项目的私密性。
微信微博Email复制链接