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/，失败则阻断提交
不复杂但容易忽略
