SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场docs-from-code

docs-from-code

写作与研究

查看项目

更新于 10-16 02:20

技能介绍

用途

docs-from-code 是一个技术文档生成技能，定位为技术写作者。它的核心目标是根据代码库中实际存在的函数、路由、类型、Schema 和架构，生成准确、对开发者友好的文档，包括 README.md 和 API 参考文档。它强调不编造代码：如果找不到清晰描述，就写 [Description needed]，认为准确但稀疏的文档优于自信但错误的文档。

主要能力

  • 使用 graphify 构建代码库知识图谱，再基于图谱撰写文档。
  • graphify 使用 tree-sitter AST（支持 20 种语言，不使用 LLM）分析代码结构，并使用 Claude 子代理对文档和注释进行语义理解。
  • 生成 graphify-out/ 目录，包含 GRAPH_REPORT.md（god nodes、社区聚类、意外连接、建议问题）和 graph.json（完整可查询知识图谱，持久化，SHA256 缓存）。
  • 支持针对特定文档章节的定向查询，例如 API 路由、数据模型、认证流程、入口点。
  • 查询结果中的关系会标记为 EXTRACTED（源码中发现）或 INFERRED（带置信度分数）。
  • 支持读取现有文档（README.md、docs/API.md、CHANGELOG.md），决定生成完整 README、仅更新过时章节，或询问用户是否重写。
  • 提供输出模板（references/output-template.md），用于生成 README 和 API 参考。
  • 支持在生成后清理临时文件，并可选择创建 GitHub PR。

使用方式

工作流程分为五步：

  1. 安装 graphify 并构建知识图谱。命令为 pip install graphifyy 和 graphify . --no-viz。--no-viz 跳过 HTML 输出，只需要 GRAPH_REPORT.md 和 graph.json。如果 graphify 失败，进入回退方案：TypeScript/JS 项目使用 cd <skill-directory>/scripts && npm install 和 npx ts-node extract_ts.ts <project-root> <project-root>/.docs-extract.json；Python 项目使用 python3 <skill-directory>/scripts/extract_py.py <project-root> <project-root>/.docs-extract.json。回退输出的框架特定说明见 references/extraction-guide.md。

  2. 完整阅读 graphify-out/GRAPH_REPORT.md，获取 god nodes、社区聚类、意外连接和建议问题。然后运行定向查询，例如 graphify query "show all API routes and endpoints" --graph graphify-out/graph.json、graphify query "what are the main data models and types?" --graph graphify-out/graph.json、graphify query "how does authentication work?" --graph graphify-out/graph.json、graphify query "what is the entry point and how is the app initialised?" --graph graphify-out/graph.json。

  3. 阅读现有文档，检查 README.md、docs/API.md 或 API.md、CHANGELOG.md，决定生成策略。

  4. 生成文档。README 的项目描述来自 package.json 或 pyproject.toml 的 description 加上 GRAPH_REPORT.md 的 god nodes 摘要；架构章节使用 god nodes 和社区聚类；安装和快速开始来自入口点文件以及 package.json 或 Makefile 中的脚本。API 参考（docs/API.md）来自 graphify 查询输出，按资源分组，每个路由包含方法、路径、描述、请求/响应结构和 curl 示例。没有 docstring 的内容标记为 [Description needed]。

  5. 写入文件、清理并打开 PR。写入 README.md 和 docs/API.md，清理 rm -rf graphify-out/ .docs-extract.json，询问用户是否打开 GitHub PR。如果同意，执行 git checkout -b docs/auto-generated-$(date +%Y%m%d)、git add README.md docs/、git commit -m "docs: auto-generate README and API reference from codebase"、gh pr create --title "docs: auto-generated README and API reference" --body "Generated by docs-from-code skill using graphify knowledge graph. All routes and types verified against source."。

开始前需要确认处于代码库目录内。如果用户指向远程仓库，先克隆。如果都没有，询问项目目录或仓库 URL。

适用场景

  • 为没有 README 的项目生成完整 README。
  • 更新已有 README 中过时的 API 章节。
  • 为项目生成 API 参考文档。
  • 需要文档与代码库实际结构保持一致，避免编造。

限制

  • 不编造代码或行为；找不到描述时写 [Description needed]。
  • INFERRED 关系需要标注不确定性，例如使用“likely”或“appears to”。
  • 需要先安装 graphify 或使用回退提取脚本。
  • 回退方案目前提供 TypeScript/JS 和 Python 的提取脚本。
  • 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。