用途:为用户提供 Python 代码的文档生成能力,当用户提出“document this code”“generate docs”,或需要从 Python 模块生成 API 文档、带用法示例的 README、读取 docstring 与类型签名时使用。
主要能力:递归分析目录中的 .py 文件或指定文件列表;用 AST 或 inspect 解析源码,提取模块级 docstring、类定义与类 docstring、函数与方法签名及类型提示、docstring 内容(支持 Google、NumPy、Sphinx 格式);按模块、类、方法、函数层级组织,输出结构一致的 Markdown,并可按需生成目录和用法示例。
输出结构:以“# 模块名”开头,附模块 docstring 简介;随后按“## Classes”“## Functions”分组;类下列出方法签名与简要说明;函数签名为 function_name(param: type) -> return_type,并列出参数与返回值说明,最后给出 Usage Examples(取自 docstring 示例或基础用法)。
用法:输入单个 Python 文件路径、目录路径(递归处理 .py 文件)或具体文件列表;基本文档生成无需外部依赖,优先使用标准库 ast、inspect、pathlib。
质量规则:在有意义时保留原 docstring 格式;签名中突出类型提示;将同类项分组;大模块添加目录;默认跳过下划线开头的私有成员,除非明确要求;缺少 docstring 时标注“No description provided”。
限制与错误处理:遇语法错误文件跳过并记录警告;缺失类型提示时优雅处理;未找到 docstring 仍继续处理并提示;处理前校验路径存在。资料未提供具体安装命令、收费信息或平台兼容性细节。