Python 函数文档规范化核心是用 Google/NumPy 风格 docstring，明确 Args、Returns、Raises、Examples，同步类型提示与语义说明，配合 pdoc/Sphinx 生成 API 文档，并通过 pydocstyle 和 mypy 在 CI 中强制检查。
Python 函数接口文档的规范化和自动化，核心在于用标准格式写好 docstring，并借助 工具 自动生成可读性强、结构统一的 API 文档。关键不是写得多，而是写得准、结构清、工具链通。
用 Google 或 NumPy 风格写 docstring
推荐选用 Google 或 NumPy 风格（二者均被 Sphinx、pdoc、pydoc 等主流工具原生支持），避免自由格式。它们结构清晰、字段明确，利于解析与生成。
- 参数（Args）：每行一个参数，格式为
param_name (type): description，类型建议用 Python 原生类型或 typing 模块中的标注（如str、Optional[List[int]]） - 返回值（Returns）：注明类型和含义，多返回值用元组形式说明，例如
(int, str): 用户 ID 和用户名 - 异常（Raises）：只列明函数主动抛出的异常，不写底层未捕获异常
- 示例（Examples）：放在末尾，用 doctest 兼容格式，方便后续做轻量验证
在代码中同步维护类型提示与 docstring
类型提示（type hints）不是 docstring 的替代品，而是互补关系。函数签名已声明类型时，docstring 中不必重复写类型，但需补充语义说明——比如 timeout: int 是“超时秒数，0 表示永不超时”。
- 若使用
def func(x: Optional[str] = None)，docstring 中应解释x=None代表“跳过校验”还是“使用默认配置” - 避免 docstring 里写
x (Optional[str]): 输入字符串这种冗余描述，重点说清业务含义和边界行为 - IDE（如 PyCharm、VS Code）能同时读取类型提示和 docstring，双管齐下提升调用端体验
用 pdoc 或 Sphinx 自动生成 HTML/API 文档
轻量项目首选pdoc：安装快、零配置、直接输出 HTML，支持跨模块跳转和源码链接。
立即学习“Python 免费学习笔记（深入）”；
- 命令行一键生成：
pdoc --html --output-dir docs mypackage - 生成结果自动提取模块、函数、类结构，按层级组织，点击即看源码和 docstring 渲染效果
- 如需定制样式或集成进 CI/CD，可用
sphinx+sphinx-autodoc，配合conf.py控制模块过滤、排序、模板
注意：所有待生成文档的模块必须能被 Python import（即路径正确、__init__.py 合理），否则工具无法解析。
把文档检查纳入开发流程
靠自觉容易遗漏，建议用工具约束质量：
- 用
pydocstyle检查 docstring 是否符合 PEP 257，例如缺失 Returns、参数描述错位、空行不规范等 - 用
mypy或pyright确保类型提示与实际逻辑一致，避免 docstring 写对了但代码跑错 - 在 pre-commit 或 CI 中加入检查步骤，例如：
pydocstyle mypackage/ && mypy mypackage/，失败则阻断提交
不复杂但容易忽略
