06 - 文档生成¶
代码文档、API文档、使用说明
📖 章节概述¶
本章将深入介绍如何使用AI生成文档，包括代码文档、API文档、使用说明以及实际应用场景。通过详细的代码示例和实践指导，帮助读者掌握AI文档生成的核心技能。
🎯 学习目标¶
完成本章后，你将能够：
- 深入理解文档生成的技术原理
- 掌握代码文档的生成方法
- 学会API文档的生成技巧
- 理解使用说明的编写方法
- 能够使用AI生成高质量的文档
- 掌握文档自动化的最佳实践
1. 代码文档¶
1.1 文档类型¶
技术原理： 代码文档帮助开发者理解代码的功能、用法和实现细节。主要类型包括：
- 模块文档：描述模块的功能和用途
- 类文档：描述类的属性和方法
- 函数文档：描述函数的参数、返回值和用法
- 类型文档：描述类型定义和接口
代码示例 - 文档生成器：
Python
import openai
from typing import Dict, List
class DocumentationGenerator:
"""文档生成器"""
def __init__(self, api_key: str):
self.client = openai.OpenAI(api_key=api_key)
def generate_module_docstring(self, code: str,
module_name: str = None) -> str:
"""
生成模块文档字符串
Args:
code: 模块代码
module_name: 模块名称
"""
prompt = f"""请为以下Python模块生成完整的文档字符串：
~~~python
{code}
~~~
要求：
1. 使用Google风格或NumPy风格的docstring
2. 包含模块概述
3. 列出主要类和函数
4. 说明模块的用途
5. 添加使用示例
6. 添加依赖说明
7. 添加作者和版本信息
请提供完整的、规范的文档字符串。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个Python文档专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
def generate_class_docstring(self, code: str,
class_name: str = None) -> str:
"""
生成类文档字符串
Args:
code: 类代码
class_name: 类名
"""
prompt = f"""请为以下Python类生成完整的文档字符串：
````python
{code}
````
要求：
1. 使用Google风格或NumPy风格的docstring
2. 包含类概述
3. 列出所有属性
4. 列出所有方法
5. 说明每个方法的参数和返回值
6. 添加使用示例
7. 添加继承关系说明
请提供完整的、规范的文档字符串。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个Python文档专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
def generate_function_docstring(self, code: str,
function_name: str = None) -> str:
"""
生成函数文档字符串
Args:
code: 函数代码
function_name: 函数名
"""
prompt = f"""请为以下Python函数生成完整的文档字符串：
````python
{code}
````
要求：
1. 使用Google风格或NumPy风格的docstring
2. 包含函数概述
3. 列出所有参数及其类型和说明
4. 说明返回值及其类型
5. 列出可能抛出的异常
6. 添加使用示例
7. 添加注意事项和限制
请提供完整的、规范的文档字符串。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个Python文档专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
# 使用示例
if __name__ == "__main__":
generator = DocumentationGenerator(api_key="your_api_key_here")
# 示例代码
code = """
class Calculator:
def __init__(self):
self.history = []
def add(self, a: float, b: float) -> float:
result = a + b
self.history.append(('add', a, b, result))
return result
def subtract(self, a: float, b: float) -> float:
result = a - b
self.history.append(('subtract', a, b, result))
return result
def get_history(self) -> list:
return self.history.copy()
def calculate_average(numbers: list) -> float:
if not numbers:
raise ValueError("Numbers list cannot be empty")
return sum(numbers) / len(numbers)
"""
# 生成类文档
print("生成类文档：")
class_doc = generator.generate_class_docstring(code, "Calculator")
print(class_doc)
# 生成函数文档
print("\n生成函数文档：")
func_doc = generator.generate_function_docstring(code, "calculate_average")
print(func_doc)
1.2 文档格式¶
代码示例 - 多格式文档生成器：
Python
import openai
class MultiFormatDocGenerator:
"""多格式文档生成器"""
def __init__(self, api_key: str):
self.client = openai.OpenAI(api_key=api_key)
def generate_google_style(self, code: str) -> str:
"""
生成Google风格文档
Args:
code: 代码
"""
prompt = f"""请为以下代码生成Google风格的文档：
````python
{code}
````
Google风格格式：
Args:
arg1: Description
arg2: Description
Returns:
Description
Raises:
Exception: Description
Examples:
>>> Example
Result
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个Google风格文档专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
def generate_numpy_style(self, code: str) -> str:
"""
生成NumPy风格文档
Args:
code: 代码
"""
prompt = f"""请为以下代码生成NumPy风格的文档：
````python
{code}
````
NumPy风格格式：
Parameters
----------
param1 : type
Description
param2 : type
Description
Returns
-------
return_type
Description
Raises
------
Exception
Description
See Also
--------
other_func : Related function
Examples
--------
>>> Example
Result
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个NumPy风格文档专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
def generate_sphinx_style(self, code: str) -> str:
"""
生成Sphinx风格文档
Args:
code: 代码
"""
prompt = f"""请为以下代码生成Sphinx风格的文档：
````python
{code}
````
Sphinx风格格式：
:param param1: Description
:type param1: type
:param param2: Description
:type param2: type
:returns: Description
:rtype: return_type
:raises Exception: Description
.. rubric:: Examples
.. doctest::
>>> Example
Result
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个Sphinx风格文档专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
# 使用示例
if __name__ == "__main__":
generator = MultiFormatDocGenerator(api_key="your_api_key_here")
# 示例代码
code = """
def process_data(data: list, threshold: float = 0.5) -> list:
filtered_data = [item for item in data if item > threshold]
return filtered_data
"""
# 生成Google风格文档
print("Google风格文档：")
google_doc = generator.generate_google_style(code)
print(google_doc)
# 生成NumPy风格文档
print("\nNumPy风格文档：")
numpy_doc = generator.generate_numpy_style(code)
print(numpy_doc)
# 生成Sphinx风格文档
print("\nSphinx风格文档：")
sphinx_doc = generator.generate_sphinx_style(code)
print(sphinx_doc)
2. API文档¶
2.1 文档内容¶
技术原理： API文档描述API的功能、用法和规范。主要内容包括：
- 端点说明：API端点的URL和HTTP方法
- 请求参数：请求的参数和格式
- 响应格式：响应的数据结构和格式
- 错误代码：可能的错误代码和含义
- 认证方式：API的认证机制
- 使用示例：API调用的示例代码
代码示例 - API文档生成器：
Python
import openai
class APIDocGenerator:
"""API文档生成器"""
def __init__(self, api_key: str):
self.client = openai.OpenAI(api_key=api_key)
def generate_openapi_spec(self, api_description: str) -> str:
"""
生成OpenAPI规范
Args:
api_description: API描述
"""
prompt = f"""请为以下API生成完整的OpenAPI 3.0规范：
API描述：
{api_description}
要求：
1. 包含所有端点
2. 定义请求和响应模型
3. 添加认证配置
4. 添加参数验证规则
5. 添加错误响应定义
6. 添加示例请求和响应
7. 遵循OpenAPI 3.0规范
请提供完整的、有效的OpenAPI YAML或JSON规范。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个OpenAPI规范专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
def generate_api_documentation(self, api_spec: str,
output_format: str = "markdown") -> str:
"""
生成API文档
Args:
api_spec: API规范
output_format: 文档格式（markdown/html/restructuredtext）
"""
prompt = f"""请为以下API规范生成完整的API文档：
API规范：
{api_spec}
要求：
1. 使用{output_format}格式
2. 包含API概述
3. 列出所有端点及其详细信息
4. 包含请求和响应示例
5. 包含认证说明
6. 包含错误代码说明
7. 添加快速开始指南
8. 添加最佳实践建议
请提供完整的、易读的API文档。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个API文档专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
# 使用示例
if __name__ == "__main__":
generator = APIDocGenerator(api_key="your_api_key_here")
# API描述
api_description = """
用户管理API：
端点：
1. GET /api/users - 获取所有用户
- 支持分页（page, per_page参数）
- 支持过滤（status参数）
2. GET /api/users/:id - 获取单个用户
- 路径参数：id（用户ID）
3. POST /api/users - 创建用户
- 请求体：username, email, password
- 验证：username唯一，email格式正确
4. PUT /api/users/:id - 更新用户
- 路径参数：id（用户ID）
- 请求体：username, email（可选）
5. DELETE /api/users/:id - 删除用户
- 路径参数：id（用户ID）
认证：JWT Bearer Token
响应格式：
{
"id": 1,
"username": "john_doe",
"email": "john@example.com",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
错误代码：
- 400: 请求参数错误
- 401: 未授权
- 404: 用户不存在
- 409: 用户名已存在
- 500: 服务器错误
"""
# 生成OpenAPI规范
print("生成OpenAPI规范：")
openapi_spec = generator.generate_openapi_spec(api_description)
print(openapi_spec)
# 生成API文档
print("\n\n生成API文档：")
api_doc = generator.generate_api_documentation(api_description, "markdown")
print(api_doc)
2.2 文档工具¶
代码示例 - Swagger文档生成：
Python
import openai
class SwaggerDocGenerator:
"""Swagger文档生成器"""
def __init__(self, api_key: str):
self.client = openai.OpenAI(api_key=api_key)
def generate_swagger_ui_config(self, openapi_spec: str) -> str:
"""
生成Swagger UI配置
Args:
openapi_spec: OpenAPI规范
"""
prompt = f"""请为以下OpenAPI规范生成Swagger UI配置：
OpenAPI规范：
{openapi_spec}
要求：
1. 生成HTML配置文件
2. 配置Swagger UI主题
3. 配置API服务器URL
4. 配置认证方式
5. 添加自定义CSS（如果需要）
6. 添加自定义logo（如果需要）
7. 配置文档显示选项
请提供完整的Swagger UI配置。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个Swagger UI配置专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
def generate_postman_collection(self, api_spec: str) -> str:
"""
生成Postman集合
Args:
api_spec: API规范
"""
prompt = f"""请为以下API规范生成Postman集合：
API规范：
{api_spec}
要求：
1. 为每个端点创建请求
2. 配置请求方法和URL
3. 配置请求头（包括认证）
4. 配置请求体
5. 添加环境变量
6. 添加测试脚本
7. 添加预请求脚本
8. 组织为集合和文件夹
请提供完整的Postman集合JSON。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个Postman集合专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
# 使用示例
if __name__ == "__main__":
generator = SwaggerDocGenerator(api_key="your_api_key_here")
# OpenAPI规范
openapi_spec = """
openapi: 3.0.0
info:
title: User Management API
version: 1.0.0
description: API for managing users
servers:
- url: http://localhost:8000/api
description: Development server
paths:
/users:
get:
summary: Get all users
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
post:
summary: Create user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreate'
responses:
'201':
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
username:
type: string
email:
type: string
format: email
UserCreate:
type: object
required:
- username
- email
- password
properties:
username:
type: string
email:
type: string
format: email
password:
type: string
format: password
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
"""
# 生成Swagger UI配置
print("生成Swagger UI配置：")
swagger_config = generator.generate_swagger_ui_config(openapi_spec)
print(swagger_config)
# 生成Postman集合
print("\n\n生成Postman集合：")
postman_collection = generator.generate_postman_collection(openapi_spec)
print(postman_collection)
3. 使用说明¶
3.1 安装指南¶
代码示例 - 安装文档生成器：
Python
import openai
from typing import Dict
class InstallationDocGenerator:
"""安装文档生成器"""
def __init__(self, api_key: str):
self.client = openai.OpenAI(api_key=api_key)
def generate_installation_guide(self, project_info: Dict) -> str:
"""
生成安装指南
Args:
project_info: 项目信息字典
"""
prompt = f"""请为以下项目生成完整的安装指南：
项目信息：
- 名称：{project_info.get('name', 'Unknown')}
- 描述：{project_info.get('description', 'Unknown')}
- 语言：{project_info.get('language', 'Unknown')}
- 框架：{project_info.get('framework', 'Unknown')}
- 依赖：{project_info.get('dependencies', [])}
要求：
1. 包含系统要求
2. 包含依赖安装步骤
3. 包含项目安装步骤
4. 包含配置说明
5. 包含验证步骤
6. 包含常见问题和解决方案
7. 添加不同操作系统的安装说明（如果适用）
8. 使用清晰的步骤和命令
9. 添加代码块和示例
请提供完整的、易读的安装指南。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个安装文档专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
def generate_docker_setup(self, project_info: Dict) -> str:
"""
生成Docker安装指南
Args:
project_info: 项目信息字典
"""
prompt = f"""请为以下项目生成Docker安装指南：
项目信息：
- 名称：{project_info.get('name', 'Unknown')}
- 语言：{project_info.get('language', 'Unknown')}
- 框架：{project_info.get('framework', 'Unknown')}
- 端口：{project_info.get('port', '8000')}
要求：
1. 生成Dockerfile
2. 生成docker-compose.yml
3. 包含构建说明
4. 包含运行说明
5. 包含环境变量配置
6. 包含数据持久化配置
7. 添加网络配置
8. 添加使用示例
请提供完整的Docker配置和说明。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个Docker配置专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
# 使用示例
if __name__ == "__main__":
generator = InstallationDocGenerator(api_key="your_api_key_here")
# 项目信息
project_info = {
"name": "MyAwesomeApp",
"description": "An awesome web application",
"language": "Python",
"framework": "Flask",
"dependencies": [
"Flask>=2.0.0",
"SQLAlchemy>=1.4.0",
"python-dotenv>=0.19.0"
],
"port": "5000"
}
# 生成安装指南
print("生成安装指南：")
install_guide = generator.generate_installation_guide(project_info)
print(install_guide)
# 生成Docker安装指南
print("\n\n生成Docker安装指南：")
docker_guide = generator.generate_docker_setup(project_info)
print(docker_guide)
3.2 使用示例¶
代码示例 - 示例代码生成器：
Python
import openai
class ExampleGenerator:
"""示例代码生成器"""
def __init__(self, api_key: str):
self.client = openai.OpenAI(api_key=api_key)
def generate_usage_examples(self, api_spec: str) -> str:
"""
生成使用示例
Args:
api_spec: API规范
"""
prompt = f"""请为以下API生成完整的使用示例：
API规范：
{api_spec}
要求：
1. 为每个端点生成示例
2. 使用Python requests库
3. 使用JavaScript fetch API
4. 使用curl命令
5. 包含认证示例
6. 包含错误处理示例
7. 包含完整的请求和响应
8. 添加注释说明
9. 提供实际可运行的代码
请提供完整的、实用的使用示例。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个API使用示例专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
def generate_tutorial(self, topic: str,
complexity: str = "beginner") -> str:
"""
生成教程
Args:
topic: 教程主题
complexity: 复杂度级别
"""
prompt = f"""请生成一个{complexity}级别的教程：
主题：{topic}
教程结构：
1. 学习目标
2. 前置知识
3. 核心概念
4. 实战示例
5. 练习题
6. 扩展阅读
要求：
1. 使用清晰的步骤说明
2. 提供完整的代码示例
3. 添加代码注释
4. 包含输出示例
5. 添加常见问题
6. 使用适合{complexity}的语言
7. 提供实际可运行的代码
请提供完整的、易懂的教程。
"""
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "你是一个技术教程专家。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return response.choices[0].message.content
# 使用示例
if __name__ == "__main__":
generator = ExampleGenerator(api_key="your_api_key_here")
# API规范
api_spec = """
用户管理API：
端点：
- GET /api/users - 获取所有用户
- POST /api/users - 创建用户
- PUT /api/users/:id - 更新用户
- DELETE /api/users/:id - 删除用户
认证：JWT Bearer Token
"""
# 生成使用示例
print("生成使用示例：")
examples = generator.generate_usage_examples(api_spec)
print(examples)
# 生成教程
print("\n\n生成教程：")
tutorial = generator.generate_tutorial("使用Flask构建REST API", "beginner")
print(tutorial)
4. 练习题¶
基础练习¶
- 生成函数文档
- 选择函数
- 生成文档字符串
- 验证格式
进阶练习¶
- 生成完整API文档
- 分析API规范
- 生成OpenAPI规范
- 生成使用示例
5. 最佳实践¶
✅ 推荐做法¶
- 保持更新
- 文档与代码同步
- 及时更新文档
-
记录变更历史
-
清晰易懂
- 使用简洁的语言
- 提供示例代码
- 添加图表和流程图
❌ 避免做法¶
- 文档过时
- 定期更新文档
- 移除过时内容
- 保持文档准确性
6. 常见问题¶
Q1: 如何保持文档与代码同步？¶
A: 同步方法： - 自动化工具：使用工具自动生成文档 - 版本控制：将文档与代码一起提交 - CI/CD集成：在CI/CD中验证文档 - 定期审查：定期检查文档准确性
Q2: 如何提高文档质量？¶
A: 提高质量的方法： - 用户反馈：收集用户对文档的反馈 - 可用性测试：测试文档的可用性 - 同行评审：让团队成员评审文档 - 持续改进：根据反馈持续改进
7. 总结¶
本章深入介绍了文档生成的核心内容，包括：
- 代码文档：模块文档、类文档、函数文档
- API文档：OpenAPI规范、Swagger配置
- 使用说明：安装指南、使用示例、教程
通过本章的学习，你应该能够使用AI生成高质量的文档了。
8. 下一步¶
继续学习07-实战项目，通过完整项目巩固所学知识。