符合PEP标准、兼容多IDE的Python Docstrings当前正确格式是什么？

1. Google风格（应用最广泛，IDE友好） #

这是当前工业界和开源项目中使用频率最高的格式，结构简洁易读，所有主流IDE都能完美解析鼠标悬停的参数提示，完全符合你的需求。格式示例：

def calculate_area(length: float, width: float) -> float:
    """计算矩形的面积

    Args:
        length (float): 矩形的长度，必须大于0
        width (float): 矩形的宽度，必须大于0

    Returns:
        float: 计算得到的矩形面积

    Raises:
        ValueError: 当长度或宽度小于等于0时抛出
    """
    if length <= 0 or width <= 0:
        raise ValueError("长度和宽度必须大于0")
    return length * width

• 符合PEP 257基础规范，搭配PEP 484的类型提示后，兼容性覆盖Python 3.6及以上版本
• VS Code（Python插件）、PyCharm默认支持解析，鼠标悬停直接显示参数说明
• Read the Docs通过sphinx.ext.napoleon插件可完美渲染成专业文档

2. reStructuredText（Sphinx原生，文档渲染首选） #

这是Sphinx的原生格式，也是Read the Docs的默认支持格式，适合需要生成正式文档的场景，同样被所有主流IDE兼容。格式示例：

def calculate_area(length: float, width: float) -> float:
    """计算矩形的面积

    :param float length: 矩形的长度，必须大于0
    :param float width: 矩形的宽度，必须大于0
    :return float: 计算得到的矩形面积
    :raises ValueError: 当长度或宽度小于等于0时抛出
    """
    if length <= 0 or width <= 0:
        raise ValueError("长度和宽度必须大于0")
    return length * width

• 对应你提到的Sphinx格式(1)，格式(2)的:py:param是更严谨的域声明，日常开发用格式(1)足够
• 无需额外插件，Sphinx和Read the Docs可直接渲染
• IDE支持鼠标悬停解析参数，兼容Python 3.6+

3. 其他格式的适用场景 #

• NumPy风格：更适合科学计算领域的项目，结构详细但相对繁琐，IDE支持尚可，但通用性不如前两种
• Parameters: param (type): description格式：属于Google风格的变体，仅将Args替换为Parameters，同样被支持，但Args是行业更通用的约定

核心注意事项 #

• 务必结合PEP 484的类型提示（如length: float），即使docstring中已标注类型，类型提示能让IDE和工具的解析更精准，同时兼容Python 3.6及以上版本
• 项目内保持docstring格式统一是首要原则

内容的提问来源于stack exchange，提问作者thethiny