Python函数文档自动生成_规范说明【指导】

python函数文档自动生成依赖三重双引号包围的规范docstring，主流工具仅识别”””…”””格式；推荐google/numpy风格，需明确标注Args、Returns、Raises等字段。

python函数文档自动生成依赖规范的docstring写法，主流工具（如sphinx、pdoc、pydoc）都按约定格式解析，不按规范写，生成的文档会缺失参数、返回值或格式混乱。

必须使用三重双引号包围docstring

单引号、三重单引号或非三重字符串均不被标准工具识别。函数定义后紧接的字符串必须是red”>”””…”””，且顶格或与def对齐（推荐顶格）。

• ✅ 正确：

  def add(a, b):
      """Return the sum of a and b."""
      return a + b

• ❌ 错误：

  def add(a, b):
      'Return the sum of a and b.'  # 单引号不解析
      return a + b

推荐采用google或NumPy风格（非reStructuredText原生语法）

Sphinx配合sphinx.ext.napoleon插件可自动转换Google/NumPy风格为html文档，比纯reST更易读、少出错。核心字段需明确标注：

• Args: 每个参数占一行，格式为name (type): description，类型可省略但建议保留
• Returns: 写明返回值类型和含义，多返回值用括号说明，如(int, str)
• Raises: 列出可能抛出的异常及触发条件

示例：

立即学习“Python免费学习笔记（深入）”；

def 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")
    # ...

函数签名与docstring参数必须严格一致

参数名拼写、顺序、是否带默认值，都要和def行完全匹配。工具不会做模糊匹配或推断。

• 若函数定义为def process(items: list, /, prefix: str = “v1”)，docstring中Args:就必须分两行写清位置参数items和仅限关键字参数prefix，并注明默认值
• 省略prefix或写成pre会导致该参数在生成文档中消失

避免空行割裂、保持语义连贯

docstring首行是简短摘要（一句话），之后空一行再写详细说明。字段块（Args/Returns等）之间不加空行，字段内部可换行但不要空行隔开。

• ✅ 首行摘要 + 空行 + 详细说明 + 字段块（紧凑排列）
• ❌ 在Args和Returns之间插入空行，部分工具会截断后续内容