🚀 code2doc：用 AI 大模型自动生成 Python API 文档

告别手写文档的痛苦，让 AI 帮你把代码变成专业文档！

📖 阅读提示

  • 目标读者：Python 开发者、技术文档维护者、开源项目作者
  • 预计阅读：15 分钟
  • 配套代码：文中所有代码均可直接运行
  • 技术要求：Python 3.8+，基础 AST 知识（可选）

📋 目录

  1. 前言：为什么需要自动化文档生成
  2. 工具概览：code2doc 能做什么
  3. 快速开始：5 分钟上手
  4. 核心原理：AST + LLM 双引擎架构
  5. 深入实战：完整使用场景
  6. 高级技巧：自定义与扩展
  7. 最佳实践：写出 AI 友好的代码
  8. 常见问题 FAQ
  9. 总结与展望

🎯 前言：为什么需要自动化文档生成

文档之痛

作为开发者，你是否经历过这些场景？

场景一：代码写完了，文档还没动笔
├── 距离 deadline 还有 2 小时
├── README 只有一行 "TODO: 写文档"
└── 内心 OS：算了，先上线再说...

场景二：文档写完了，代码改了
├── 新加了 3 个参数
├── 删除了 2 个方法
├── 文档？什么文档？

场景三：接手别人的代码
├── 函数名：do_something()
├── 注释：无
├── 文档：404 Not Found
└── 你的表情：💀

统计数据告诉我们：

场景 比例
文档与代码不同步 68%
完全没有文档的函数 42%
开发者讨厌写文档 89%
用户因文档不全放弃使用 35%

解决方案

如果有一个工具能够：

  • ✅ 自动解析代码结构（类、函数、参数、返回值）
  • ✅ 智能生成功能描述和使用示例
  • ✅ 一键输出专业的 Markdown 文档
  • ✅ 支持多种 AI 大模型后端

这就是 code2doc 的设计目标。

🔍 工具概览：code2doc 能做什么

核心功能

┌─────────────────────────────────────────────────────────────┐
│                      code2doc 架构                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Python 源码  ──→  AST 解析器  ──→  结构化信息            │
│       │                                    │                │
│       │                                    ▼                │
│       │                            ┌──────────────┐        │
│       │                            │   LLM 增强   │        │
│       │                            │  (可选)      │        │
│       │                            └──────┬───────┘        │
│       │                                   │                │
│       │                                   ▼                │
│       └──────────────────→  Markdown 文档生成器            │
│                                           │                │
│                                           ▼                │
│                                   📄 专业 API 文档          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

功能特性

特性 说明
🔬 AST 深度解析 提取类、方法、函数、参数、返回值、装饰器
🤖 LLM 智能增强 自动生成功能描述、使用示例、注意事项
🔌 多模型支持 智谱 GLM、DeepSeek、OpenAI 兼容接口
📝 Markdown 输出 开箱即用的专业文档格式
🎛️ 灵活可控 可选是否使用 LLM，支持离线模式
💻 CLI + API 命令行工具 + Python 编程接口双支持

输入输出示例

输入：一个 Python 文件

# my_module.py
class DataProcessor:
    """高性能数据处理器"""
    
    def process(self, data: list) -> dict:
        """处理数据并返回统计结果"""
        return {"count": len(data)}

输出：专业的 Markdown 文档

# 📦 my_module - API 完全指南

## 🎯 核心类

### DataProcessor
> 高性能数据处理器

| 方法 | 说明 |
|------|------|
| `process()` | 处理数据并返回统计结果 |

#### `process(self, data: list) -> dict`
处理数据并返回统计结果
...

🚀 快速开始：5 分钟上手

Step 1: 环境准备

# 确保 Python 版本 >= 3.8
python --version

# 安装依赖
pip install openai python-dotenv

Step 2: 配置 API Key

在项目根目录创建 .env 文件：

# 智谱 API（推荐，国内访问快）
ZHIPU_API_KEY=your_api_key_here

# 或者使用 DeepSeek
DEEPSEEK_API_KEY=your_api_key_here

# 或者使用 OpenAI
OPENAI_API_KEY=your_api_key_here

Step 3: 基础使用

命令行方式：

# 最简用法：生成 my_module.md
python code2doc.py my_module.py

# 指定输出路径
python code2doc.py my_module.py -o docs/api.md

# 使用 DeepSeek 模型
python code2doc.py my_module.py --provider deepseek

# 不使用 LLM（离线模式）
python code2doc.py my_module.py --no-llm

# 显示详细信息
python code2doc.py my_module.py -v

Python API 方式：

from code2doc import code2doc

# 一行代码生成文档
doc = code2doc("my_module.py", verbose=True)

# 自定义选项
doc = code2doc(
    source_path="my_module.py",
    output_path="docs/api.md",
    provider="zhipu",      # 'zhipu', 'deepseek', 'openai'
    use_llm=True,          # 是否使用大模型增强
    verbose=True           # 显示详细日志
)

Step 4: 查看结果

# 查看生成的文档
cat my_module.md

# 或在 VS Code 中预览
code my_module.md

🧠 核心原理：AST + LLM 双引擎架构

第一引擎：AST 代码解析

AST (Abstract Syntax Tree，抽象语法树) 是 Python 代码的结构化表示。

# 示例代码
def greet(name: str) -> str:
    """问候函数"""
    return f"Hello, {name}!"

经过 AST 解析后，我们得到：

FunctionDef
├── name: "greet"
├── args: [Arg(name="name", annotation="str")]
├── returns: "str"
├── docstring: "问候函数"
└── body: [Return(...)]

code2doc 的 AST 解析核心代码：

import ast

class CodeParser:
    """Python 代码解析器"""
    
    def __init__(self, source_code: str):
        self.source_code = source_code
        self._tree = ast.parse(source_code)
    
    def parse(self):
        """解析源代码，提取结构信息"""
        module_info = ModuleInfo(
            docstring=ast.get_docstring(self._tree)
        )
        
        for node in self._tree.body:
            if isinstance(node, ast.ClassDef):
                module_info.classes.append(
                    self._parse_class(node)
                )
            elif isinstance(node, ast.FunctionDef):
                module_info.functions.append(
                    self._parse_function(node)
                )
        
        return module_info

第二引擎：LLM 智能增强

AST 只能提取代码的"骨架"，而 LLM 可以理解代码的"灵魂"。

AST 提取的信息：
├── 函数名：calculate_discount
├── 参数：price, rate
├── 返回值：float
└── 文档字符串：计算折扣

LLM 增强后的描述：
├── 功能概述：根据原价和折扣率计算最终价格
├── 使用场景：电商促销、会员优惠计算
├── 示例代码：final_price = calculate_discount(100, 0.8)  # 80.0
└── 注意事项：rate 应在 0-1 之间

code2doc 的 LLM 增强核心代码：

class LLMClient:
    """大模型客户端"""
    
    PROVIDERS = {
        'zhipu': {
            'base_url': 'https://open.bigmodel.cn/api/paas/v4',
            'env_key': 'ZHIPU_API_KEY',
            'default_model': 'glm-4-flash'
        },
        'deepseek': {
            'base_url': 'https://api.deepseek.com',
            'env_key': 'DEEPSEEK_API_KEY', 
            'default_model': 'deepseek-chat'
        }
    }
    
    def __init__(self, provider='zhipu'):
        config = self.PROVIDERS[provider]
        self.client = OpenAI(
            api_key=os.getenv(config['env_key']),
            base_url=config['base_url']
        )
        self.model = config['default_model']
    
    def generate(self, prompt: str) -> str:
        """调用大模型生成文本"""
        response = self.client.chat.completions.create(
            model=self.model,
            messages=[{"role": "user", "content": prompt}]
        )
        return response.choices[0].message.content

数据流图

┌──────────────┐
│  Python 源码  │
└──────┬───────┘
       │
       ▼
┌──────────────┐     ┌──────────────┐
│  AST 解析器   │ ──→ │  ModuleInfo  │ (类、函数、参数...)
└──────────────┘     └──────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
              ▼             ▼             ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │ ClassInfo│  │FunctionInfo│ │ConstInfo │
        └────┬─────┘  └─────┬────┘  └────┬─────┘
             │              │             │
             └──────────────┼─────────────┘
                            │
                            ▼
                    ┌──────────────┐
                    │  LLM 增强器   │ (可选)
                    └──────┬───────┘
                           │
                           ▼
                    ┌──────────────┐
                    │ 文档生成器    │
                    └──────┬───────┘
                           │
                           ▼
                    ┌──────────────┐
                    │ Markdown 文档│
                    └──────────────┘

💡 深入实战：完整使用场景

场景 1：为开源项目生成 API 文档

"""
场景：你开发了一个工具库，需要生成完整的 API 文档
"""
from code2doc import code2doc
from pathlib import Path

# 批量处理整个目录
src_dir = Path("my_library")
docs_dir = Path("docs/api")
docs_dir.mkdir(parents=True, exist_ok=True)

for py_file in src_dir.glob("**/*.py"):
    if py_file.name.startswith("_"):
        continue  # 跳过私有模块
    
    output = docs_dir / f"{py_file.stem}.md"
    code2doc(str(py_file), str(output), verbose=True)
    print(f"✅ {py_file.name} -> {output.name}")

场景 2：CI/CD 自动化文档更新

# .github/workflows/docs.yml
name: Auto Update Docs

on:
  push:
    paths:
      - 'src/**/*.py'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      
      - name: Install dependencies
        run: pip install openai python-dotenv
      
      - name: Generate docs
        env:
          ZHIPU_API_KEY: ${{ secrets.ZHIPU_API_KEY }}
        run: |
          for file in src/*.py; do
            python code2doc.py "$file" -o "docs/$(basename ${file%.py}).md"
          done
      
      - name: Commit changes
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add docs/
          git commit -m "docs: auto update API documentation" || true
          git push

场景 3：交互式文档生成

"""
场景：根据用户选择生成定制化文档
"""
from code2doc import CodeParser, DocGenerator, LLMClient

def interactive_doc_gen(source_path: str):
    # 1. 解析代码
    with open(source_path) as f:
        parser = CodeParser(f.read(), source_path)
    module = parser.parse()
    
    # 2. 让用户选择要文档化的内容
    print(f"\n📦 模块: {module.name}")
    print(f"   发现 {len(module.classes)} 个类, {len(module.functions)} 个函数\n")
    
    print("请选择要生成文档的内容：")
    for i, cls in enumerate(module.classes, 1):
        print(f"  [{i}] 类: {cls.name}")
    
    choice = input("\n输入序号（多个用逗号分隔，或 'all'）: ")
    
    # 3. 根据选择生成文档
    if choice.lower() == 'all':
        selected = module.classes
    else:
        indices = [int(x.strip()) - 1 for x in choice.split(',')]
        selected = [module.classes[i] for i in indices]
    
    # 4. 生成文档
    llm = LLMClient(provider='zhipu')
    generator = DocGenerator(llm, use_llm=True)
    
    # ... 自定义文档生成逻辑
    
    print("\n✅ 文档生成完成！")

# 使用
interactive_doc_gen("my_module.py")

🔧 高级技巧：自定义与扩展

技巧 1：自定义文档模板

class CustomDocGenerator(DocGenerator):
    """自定义文档生成器"""
    
    # 覆盖系统提示，定制 AI 生成风格
    SYSTEM_PROMPT = """你是一位幽默的技术文档作者。
    在保持专业的同时，适当加入一些有趣的比喻和梗。
    让读者在学习的同时也能会心一笑。"""
    
    def _generate_header(self, module):
        """自定义头部模板"""
        return f"""
# 🎉 {module.name} 使用手册

> 欢迎来到 {module.name} 的奇妙世界！
> 
> 这份文档将带你从入门到精通，准备好了吗？🚀
"""

技巧 2：添加新的 LLM 提供商

# 扩展 LLMClient 支持更多模型
LLMClient.PROVIDERS['claude'] = {
    'base_url': 'https://api.anthropic.com/v1',
    'env_key': 'ANTHROPIC_API_KEY',
    'default_model': 'claude-3-sonnet-20240229'
}

LLMClient.PROVIDERS['local'] = {
    'base_url': 'http://localhost:11434/v1',  # Ollama
    'env_key': 'LOCAL_API_KEY',
    'default_model': 'llama2'
}

技巧 3：提取特定类型的信息

from code2doc import CodeParser

def extract_all_apis(source_path: str):
    """提取所有公开 API"""
    with open(source_path) as f:
        parser = CodeParser(f.read(), source_path)
    
    module = parser.parse()
    
    apis = []
    
    # 收集所有公开函数
    for func in module.functions:
        if not func.is_private:
            apis.append({
                'type': 'function',
                'name': func.name,
                'signature': f"{func.name}({', '.join(a['name'] for a in func.args)})",
                'docstring': func.docstring,
                'is_async': func.is_async
            })
    
    # 收集所有公开类和方法
    for cls in module.classes:
        apis.append({
            'type': 'class',
            'name': cls.name,
            'docstring': cls.docstring,
            'methods': [m.name for m in cls.methods if not m.is_private]
        })
    
    return apis

# 使用
apis = extract_all_apis("my_module.py")
print(f"发现 {len(apis)} 个公开 API")

📝 最佳实践：写出 AI 友好的代码

想让 code2doc 生成更好的文档？从写好代码注释开始！

Do ✅ 好的文档字符串

def calculate_discount(
    original_price: float,
    discount_rate: float,
    min_price: float = 0
) -> float:
    """
    计算商品折扣后的价格
    
    根据原价和折扣率计算最终售价，支持设置最低价格保护。
    
    Args:
        original_price: 商品原价（单位：元）
        discount_rate: 折扣率，范围 0.0-1.0（如 0.8 表示八折）
        min_price: 最低价格保护，默认为 0
        
    Returns:
        float: 折扣后的价格
        
    Raises:
        ValueError: 当折扣率不在有效范围内时抛出
        
    Example:
        >>> calculate_discount(100, 0.8)
        80.0
        >>> calculate_discount(100, 0.5, min_price=60)
        60.0
    """
    if not 0 <= discount_rate <= 1:
        raise ValueError(f"折扣率必须在 0-1 之间，当前值: {discount_rate}")
    
    final_price = original_price * discount_rate
    return max(final_price, min_price)

Don’t ❌ 差的文档字符串

def calc(p, r, m=0):
    """计算价格"""  # 信息太少
    if r < 0 or r > 1:
        raise ValueError("error")  # 没有说明
    return max(p * r, m)

文档字符串检查清单

要素 说明 重要性
一句话描述 函数的核心功能 ⭐⭐⭐⭐⭐
详细说明 补充使用场景、注意事项 ⭐⭐⭐⭐
Args 参数名、类型、含义 ⭐⭐⭐⭐⭐
Returns 返回值类型和含义 ⭐⭐⭐⭐
Raises 可能抛出的异常 ⭐⭐⭐
Example 使用示例 ⭐⭐⭐⭐

❓ 常见问题 FAQ

Q1: 不使用 LLM 能生成文档吗？

可以！ 使用 --no-llm 参数即可：

python code2doc.py my_module.py --no-llm

此模式下，code2doc 仅使用 AST 解析提取代码结构，不调用任何外部 API。

Q2: 支持哪些 LLM 模型？

目前内置支持：

提供商 默认模型 特点
智谱 (zhipu) glm-4-flash 国内访问快，中文效果好
DeepSeek deepseek-chat 性价比高，代码理解强
OpenAI gpt-4o-mini 效果最好，需要代理

Q3: 如何处理大型项目？

建议分模块处理：

from pathlib import Path
from code2doc import code2doc

for py_file in Path("src").rglob("*.py"):
    if "__pycache__" not in str(py_file):
        code2doc(str(py_file), use_llm=False, verbose=True)

Q4: 文档质量不满意怎么办？

  1. 改进源代码注释：AI 很大程度依赖原有的 docstring
  2. 切换 LLM 模型：不同模型擅长领域不同
  3. 自定义 Prompt：继承 DocGenerator 修改提示词

Q5: 如何贡献代码？

欢迎 PR！重点关注：

  • 支持更多 LLM 提供商
  • 优化文档模板
  • 添加更多输出格式（如 reStructuredText）
  • 改进 AST 解析能力

🎯 总结与展望

核心收获

通过本文，你学会了：

内容 掌握程度
code2doc 的安装和基础使用 ✅ 完全掌握
AST + LLM 双引擎架构原理 ✅ 理解原理
多种实战场景的应用 ✅ 可独立实践
自定义扩展方法 ✅ 进阶技能
AI 友好代码的写法 ✅ 最佳实践

工具对比

工具 AST 解析 LLM 增强 中文支持 易用性
code2doc ✅ ✅ ✅ ⭐⭐⭐⭐⭐
Sphinx ✅ ❌ ⚠️ ⭐⭐⭐
pydoc ✅ ❌ ⚠️ ⭐⭐⭐⭐
pdoc ✅ ❌ ⚠️ ⭐⭐⭐⭐

未来展望

  • 🔜 支持更多语言（JavaScript、Go、Rust）
  • 🔜 Web UI 界面
  • 🔜 VS Code 插件
  • 🔜 自动检测文档过期并更新

📚 相关资源

如果这篇文章对你有帮助，请点赞收藏支持！有问题欢迎评论区交流！ 👋

# python # 软件工程
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

SpringBoot+Vue 乡村养老服务管理系统平台完整项目源码+SQL脚本+接口文档【Java Web毕设】

avatar AtomGit开源社区
cover

Java Web 校园生活服务平台系统源码-SpringBoot2+Vue3+MyBatis-Plus+MySQL8.0【含文档】

avatar AtomGit开源社区
cover

【2025最新】基于SpringBoot+Vue的校园健康驿站管理系统管理系统源码+MyBatis+MySQL

avatar AtomGit开源社区