⚡

Python文档生成器 doc-generator

Python文档生成器是一个自动化工具，用于将Python源代码转换为结构清晰、易于阅读的Markdown格式技术文档。它能智能解析代码文件，提取模块、类、函数的文档字符串和类型提示，自动生成包含API参考、使用示例和层次化说明的完整文档。适用于开发者、技术写作者和项目管理者，快速为Python项目生成高质量的技术文档、API参考手册和README文件，提升代码可维护性和团队协作效率。 关键词：Python文档生成，自动化文档工具，API文档生成，Markdown文档，代码文档化，Python代码分析，技术文档生成，docstring提取，开发文档，README生成

后端开发 0 次安装 0 次浏览 更新于 3/2/2026

name: doc-generator description: 通过分析Python源代码文件，提取文档字符串、类型提示和代码结构，生成Markdown格式的文档。当用户要求记录Python代码、从源代码创建API文档或生成README文件时使用。

Python 文档生成器

从Python源代码生成全面的Markdown文档。

何时使用此技能

  • 用户要求“记录此代码”或“生成文档”时
  • 从Python模块创建API文档时
  • 生成包含使用示例的README文件时
  • 将文档字符串和类型签名提取为可读格式时
  • 用户提及“文档”、“文档字符串”或“API参考”时

输入

接受以下任一输入：

  • 单个Python文件路径
  • 目录路径（递归处理.py文件）
  • 特定文件列表

输出格式

生成标准Markdown格式：

# 模块名称

来自模块文档字符串的简要描述。

## 类

### 类名

来自类文档字符串的描述。

**方法：**
- `方法名(参数: 类型) -> 返回类型`: 简要描述

## 函数

### 函数名(参数: 类型) -> 返回类型

来自文档字符串的描述。

**参数：**
- `参数` (类型): 描述

**返回：**
- 类型: 描述

## 使用示例

```python
# 从文档字符串示例中提取或生成基本用法


## 分析方法

1. **解析Python文件**：使用AST或检查
2. **提取关键元素：**
   - 模块级文档字符串
   - 类定义和文档字符串
   - 带有类型提示的函数/方法签名
   - 文档字符串内容（支持Google、NumPy、Sphinx格式）
3. **按层次组织**（模块 -> 类 -> 方法 -> 函数）
4. **生成格式清晰的Markdown**，保持一致的格式

## 质量指南

- 在有意义时保留原始文档字符串格式
- 在签名中突出显示类型提示
- 将相关项分组（所有类在一起，所有函数在一起）
- 为大型模块添加目录
- 除非明确要求，否则跳过私有成员（以下划线开头）
- 优雅地处理缺失的文档字符串（注明“未提供描述”）

## Python工具

优先使用标准库：
- `ast` 模块用于解析
- `inspect` 模块用于运行时内省
- `pathlib` 用于文件处理

基本文档生成无需外部依赖。

## 错误处理

- 跳过有语法错误的文件（记录警告）
- 优雅地处理缺失的类型提示
- 如果未找到文档字符串则发出警告，但继续处理
- 在处理前验证文件路径是否存在