Composio Python SDK 文档生成器基于 griffe 的 MDX 参考文档自动化流水线【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文聚焦 Composio 开源仓库中的 SDK 文档生成模块python/scripts/README.md 与其核心实现 generate-docs.py。该模块使用 griffe 解析 Python 源码与 docstring自动生成docs/content/reference/sdk-reference/python/下的 MDX 参考文档并配套回归测试与 CI 自动提 PR 流程。读完本文你将掌握该文档生成器的运行方式、三类核心配置EXPECTED_CLASSES、CLASS_MODULES、DECORATORS_TO_DOCUMENT的作用、MDX 产物结构以及如何在自己的 Python 项目中复用这套「源码即文档」的生成模式。一、背景为什么 SDK 参考文档需要自动生成Composio 的 Python SDKpython/composio/sdk.py是一个公开 API 面较大的包以Composio类为入口向下暴露tools、toolkits、triggers、connected_accounts、auth_configs、mcp等多个子模块对象每个对象又包含大量方法与参数。如果全部手写文档极易出现「源码改了、文档忘了同步」的问题且方法签名、参数默认值、返回类型等信息手抄成本高、错误率也高。该模块的解决方案是「源码即事实」由 griffe 直接读取源码中的类型注解与 docstring把结构化数据转换为 MDX 文件再通过 CI 在源码变更后自动生成并提交 PR。整个链条保证了参考文档与实现保持同源这也是开发者引用参考文档时能放心依赖其准确性的根本原因。二、快速开始一条命令生成全部文档按 python/scripts/README.md 中的说明在仓库根目录下执行cd python uv run --with griffe python scripts/generate-docs.py其中cd python生成脚本 generate-docs.py 位于python/scripts/下其脚本内PACKAGE_DIR SCRIPT_DIR.parent会把python/作为待分析包根目录与 griffe 的搜索路径uv run --with griffe使用 uv 临时注入 griffe 依赖后运行脚本无需预先修改项目的依赖清单。若环境中没有 griffe脚本会打印Error: griffe not installed. Run: pip install griffe并以非零状态退出见 generate-docs.py 中load_griffe()的懒加载逻辑输出目录为仓库根下的docs/content/reference/sdk-reference/python/由脚本内OUTPUT_DIR常量计算得到。运行结束后控制台会依次打印加载包、发现各个类、处理装饰器以及最终生成统计等信息例如Done! Generated N class docs index。三、工作原理三步流水线README 用三个步骤概括了整体流程结合源码可以展开为更完整的执行序列提取griffe 解析composio/**/*.py从 docstring、类型注解与类/方法结构中得到结构化数据。对应源码中griffe.load(composio, search_paths[str(PACKAGE_DIR)])的调用转换generate-docs.py将结构化数据转换为 MDX 文件——为每个公开类生成独立页面并生成索引页与导航配置输出全部文件写入docs/content/reference/sdk-reference/python/包括每个类的.mdx页面、index.mdx汇总页与meta.json导航清单。实际执行时main()函数的完整顺序如下可对照 generate-docs.py 验证懒加载 griffe校验环境清理并重建输出目录shutil.rmtreemkdir加载composio包定位sdk模块中的Composio类遍历CLASS_MODULES中的模块在成员里查找EXPECTED_CLASSES声明的类同时建立「属性名 → 类名」映射prop_to_class供Composio页面的属性交叉链接使用补充处理ADDITIONAL_CLASSES中那些不以composio.属性方式直接暴露、但仍属公开 API 的类如ToolRouterSession对每个类执行extract_class_info提取属性、方法、参数、返回值与示例处理DECORATORS_TO_DOCUMENT声明的修饰器并生成文档片段生成index.mdx与meta.json。四、配置详解三类核心配置项README 列出三个核心配置源码中还有若干辅助配置共同决定「文档化哪些内容」。4.1EXPECTED_CLASSES类名到Composio属性的映射EXPECTED_CLASSES { Tools: tools, Toolkits: toolkits, Triggers: triggers, ConnectedAccounts: connected_accounts, AuthConfigs: auth_configs, MCP: mcp, }键类名如Tools值该类在Composio实例上对应的属性名如composio.tools。该映射的意义在于生成Composio类页面时属性表格中的tools、toolkits等条目会被渲染为指向对应类页面的链接类型列显示为Tools等类名形成「入口类 → 子模块类」的交叉引用结构。实际产物可见 composio.mdx 的 Properties 表格。同时该映射也用于在 sdk.py 的__init__中确认这些属性确实由构造器初始化self.tools Tools(...)、self.toolkits Toolkits(...)等保证「文档声明的 API」与「运行时存在的 API」一一对应。4.2CLASS_MODULES类搜索范围CLASS_MODULES [ core.models.tools, core.models.toolkits, core.models.triggers, core.models.connected_accounts, core.models.auth_configs, core.models.mcp, ]脚本按点号逐级下钻 griffe 的package.members树只有出现在这些模块中的类才会被纳入文档范围。与EXPECTED_CLASSES一一对应的 6 个模块恰好覆盖了 SDK 的主要子领域工具、工具包、触发器、连接账户、认证配置与 MCP。每个类找到后其访问路径会被标记为composio.property如composio.tools并打印Found Tools (via composio.tools)之类的日志。4.3DECORATORS_TO_DOCUMENT需要文档化的修饰器DECORATORS_TO_DOCUMENT [ (before_execute, composio.core.models._modifiers), (after_execute, composio.core.models._modifiers), (before_file_upload, composio.core.models._modifiers), (schema_modifier, composio.core.models._modifiers), ]每个元组的第一个元素是装饰器函数名第二个元素是其在包内的模块路径。这 4 个装饰器全部位于 python/composio/core/models/_modifiers.py是 SDK 的自定义工具修饰能力before_execute/after_execute分别在工具执行前后改写请求参数或响应before_file_upload拦截文件上传返回新路径/URL 或False中止上传schema_modifier在运行期修改工具 schema。生成器会为每个装饰器渲染一段签名示例例如before_execute(modifier..., tools..., toolkits...)配合def my_modifier(...)占位帮助用户理解修饰器的调用形态完整说明可见 index.mdx 的 Decorators 小节。4.4 辅助配置过滤、重命名与补充源码中还定义了以下几组影响文档产物的辅助配置SKIP_CLASSES{WithLogger, SDKConfig, TProvider}过滤日志基类、SDK 配置 TypedDict 与泛型占位等内部/辅助类ADDITIONAL_CLASSES{ToolRouterSession: core.models.tool_router_session}补充那些不通过composio.属性暴露、但属于公开 API 的类源码注释特别说明SessionContextImpl因属内部实现细节而刻意不收录DISPLAY_NAME_OVERRIDES{ToolRouterSession: Session}实现「源码类名不变、文档展示名规范化为 Session」的纯展示层重命名SLUG_OVERRIDES{ToolRouterSession: session}控制输出文件名与 URL slug。正是后两组配置使 session.mdx 以Session名称对外呈现同时meta.json中登记为session页而无需对源码做破坏性改名。五、输出产物MDX 文件的结构5.1 目录清单运行生成器后docs/content/reference/sdk-reference/python/下会包含与当前仓库现状一致index.mdx汇总页含安装提示、类清单表格、Quick Start 代码示例与 Decorators 小节composio.mdx、tools.mdx、toolkits.mdx、triggers.mdx、connected-accounts.mdx、auth-configs.mdx、mcp.mdx、session.mdx每个类的独立页面meta.jsonFumadocs 导航元数据pages数组按composio → tools → ... → session的顺序声明页面与SLUG_OVERRIDES保持一致。5.2 单页结构以tools.mdx为例每个类页面由generate_class_mdx()生成典型结构为YAML frontmattertitle与descriptiondescription 取类 docstring 首段并做长度截断超过 150 字符截为 147 字符加省略号同时会把 reStructuredText 风格的双反引号 code 规范化为单反引号弃用提示若类 docstring 含.. deprecated::指令则渲染为Callout typewarn titleDeprecated警告块Properties 表格列出公开属性跳过下划线开头成员当属性名命中prop_to_class时渲染为指向类页面的 Markdown 链接类型列显示类名当属性无描述时自动降级为两列表格Methods 小节每个方法包含描述、Python 签名代码块参数按name: type输出有默认值的标记 ...、参数表格?后缀标注可选参数|转义为\|以兼容表格、返回值说明None/Any省略、示例代码块方法之间以---分隔View source 链接页面底部为每个对象输出指向源码文件行号位置的链接由 griffe 提供的filepath与lineno计算得出。以 tools.mdx 为例读者可以看到get()、execute()、proxy()、get_raw_tool_router_meta_tools()等方法的完整签名与参数表其中get()的返回类型按 provider 泛型动态推断如 OpenAIProvider 返回list[ChatCompletionToolParam]这正体现了生成器对泛型标注的忠实呈现。六、docstring 与类型的规范化处理为了让生成文档「可读、可复制」脚本对原始源码信息做了多层规范化类型清理format_type去掉typing.、typing_extensions.、composio.client.types.等前缀将Optional[X]改写为X | None把Unpack[...]简化为内部类型超过 60 字符的超长类型截断为 57 字符加...docstring 分区解析parse_docstring逐行识别:param name:、:returns:/:return:、Example区段与.. deprecated::指令分别归入 description、params、returns、examples、deprecated 字段多行描述会正确拼接示例规范化normalize_example用textwrap.dedent去除缩进若示例自身带有 python ... 围栏则剥离围栏内容避免生成「嵌套代码块」的非法 MDX。这些细节并非无关紧要——回归测试 python/tests/test_generate_docs.py 专门验证了两点Triggers.parse()生成的示例必须是可直接ast.parse的合法 Python保证「复制即用」docstring 示例中的嵌套 Markdown 围栏会被剥离不会污染最终 MDX。七、测试保障回归测试如何守护产物质量测试文件通过importlib.util.spec_from_file_location动态加载scripts/generate-docs.py不执行main()仅导入模块从而在无 griffe 的测试环境下单测解析逻辑这正是脚本把 griffe 做成懒加载的原因。测试内容test_triggers_parse_generated_example_is_valid_python用真实类的Triggers.parse.__doc__跑parse_docstring断言示例存在且可通过ast.parse语法校验防止 docstring 改动后生成不可复制的示例代码test_generated_examples_do_not_keep_nested_markdown_fences验证normalize_example会剥离示例内嵌的 python 围栏。也就是说文档生成器自身也受 CI 测试保护任何会让「生成的示例代码失配」的 docstring 变更都会在测试阶段被拦截。八、CI 自动化源码变更自动生成并提交 PRREADME 提到的.github/workflows/generate-sdk-docs.yml在仓库中真实存在其generate-python-docsjob 完整实现了「触发 → 生成 → 提 PR → 请求评审」的闭环触发条件push到next分支且路径匹配python/composio/**、python/scripts/generate-docs.py、.github/workflows/generate-sdk-docs.yml、mise.toml/mise.lock等同时支持workflow_dispatch手动触发运行步骤生成 GitHub App token → checkout → 用setup-python-uvaction 准备 uv 环境 → 执行cd python uv run --with griffe python scripts/generate-docs.py提 PR使用peter-evans/create-pull-request将docs/content/reference/sdk-reference/python/目录的变更提交为标题为docs: update Python SDK reference from source的 PRbase 分支为next并自动把提交者添加为 reviewer。值得留意的是同一个工作流还包含generate-ts-docsjob对应 TypeScript 侧的文档生成pnpm --filter composio/core generate:docs说明「源码变更自动同步 SDK 参考文档」是整个仓库的通用工程实践Python 侧只是其中一半。该工作流还约束了permissions: contents: read的最小权限原则仅在需要写回内容的 job 内放开contents: write与pull-requests: write。九、落地实践如何把该模式复用到自己的项目这套生成器的设计对任何维护 Python SDK 文档的团队都有直接借鉴价值让文档生成成为构建步骤的一部分与手写文档相比griffe 直接从类型注解与 docstring 提取信息签名与参数永远与源码同步用配置声明「文档化范围」用「类名 → 入口属性」映射和「模块列表」精确圈定公开 API配合SKIP_CLASSES屏蔽内部类避免把实现细节泄露进面向用户的参考文档展示层与源码解耦DISPLAY_NAME_OVERRIDES/SLUG_OVERRIDES这类纯展示覆盖让团队可以在不破坏源码兼容性的前提下规范化文档中的类名与 URL用测试守护生成器自身像 test_generate_docs.py 那样把「生成的示例必须可运行、生成的 MDX 必须合法」固化为自动化断言用 CI 完成闭环在源码路径变更时自动重新生成并提 PR配合人工评审让文档更新成为可追踪、可审查的常规流程。如果你需要在本仓库中查看最终产物可直接阅读 index.mdx总览与 Quick Start、composio.mdx入口类属性交叉链接以及 tools.mdx方法级参考页范式并结合 generate-docs.py 源码理解每段产物背后的生成逻辑。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考