Python函数文档自动生成依赖三重双引号包围的规范docstring，主流工具仅识别"""..."""格式；推荐Google/NumPy风格，需明确标注Args、Returns、Raises等字段。
Python函数文档自动生成依赖规范的docstring写法，主流工具（如Sphinx、pdoc、pydoc）都按约定格式解析，不按规范写，生成的文档会缺失参数、返回值或格式混乱。
必须使用三重双引号包围docstring
单引号、三重单引号或非三重字符串均不被标准工具识别。函数定义后紧接的字符串必须是
"""..."""
，且顶格或与def对齐（推荐顶格）。
✅ 正确：
❌ 错误：
推荐采用Google或NumPy风格（非reStructuredText原生语法）
Sphinx配合sphinx.ext.napoleon插件可自动转换Google/NumPy风格为HTML文档，比纯reST更易读、少出错。核心字段需明确标注：
Args:
每个参数占一行，格式为
name (type): description
，类型可省略但建议保留
Returns:
写明返回值类型和含义，多返回值用括号说明，如
(int, str)
Raises:
列出可能抛出的异常及触发条件
示例：
go语言参考手册 中文CHM版
Go 是一个开源的编程语言，它能让构造简单、可靠且高效的软件变得容易。本文给大家带来Go参考手册，需要的可以来下载！ Go是从2007年末由Robert Griesemer, Rob Pike, Ken Thompson主持开发，后来还加入了Ian Lance Taylor, Russ Cox等人，并最终于2009年11月开源，在2012年早些时候发布了Go 1稳定版本。现在Go的开发已经是完全开放的，并且拥有一个活跃的社区。 Go 语言特色 简洁、快速、安全 并行、有趣、开源 内存管理、v数组安全、编译
下载
立即学习
“
Python免费学习笔记（深入）
”；
函数签名与docstring参数必须严格一致
参数名拼写、顺序、是否带默认值，都要和def行完全匹配。工具不会做模糊匹配或推断。
若函数定义为
def process(items: list, /, prefix: str = "v1")
，docstring中
Args:
就必须分两行写清位置参数
items
和仅限关键字参数
prefix
，并注明默认值
省略
prefix
或写成
pre
会导致该参数在生成文档中消失
避免空行割裂、保持语义连贯
docstring首行是简短摘要（一句话），之后空一行再写详细说明。字段块（Args/Returns等）之间不加空行，字段内部可换行但不要空行隔开。
✅ 首行摘要 + 空行 + 详细说明 + 字段块（紧凑
排列
）
❌ 在Args和Returns之间插入空行，部分工具会截断后续内容
def add(a, b):
"""Return the sum of a and b."""
return a + bdef add(a, b):
'Return the sum of a and b.' # 单引号不解析
return a + bdef fetch_user(user_id: int) -> dict:
"""Retrieve user data by ID.
Args:
user_id (int): Unique identifier for the user.
Returns:
dict: User profile with keys 'name', 'email', and 'active'.
Raises:
ValueError: If user_id is negative.
ConnectionError: If backend service is unreachable.
"""
if user_id < 0:
raise ValueError("user_id must be non-negative")
# ...