Python结合Sphinx Autodoc/Napoleon时文档字符串格式异常原因咨询

这种格式异常是Sphinx Napoleon扩展对reStructuredText风格docstring的解析规则导致的，具体原因和解决办法如下：

核心原因 #

Napoleon虽然支持reStructuredText风格的:param/:type标签，但它对标签块的位置有严格的解析逻辑：

• 当使用这类标签时，Napoleon默认认为标签块是docstring的"结构化部分"，需要和前面的自由文本描述用空行明确分隔。如果说明文本直接跟在标签上方且没有空行，Napoleon会错误地将说明文本识别为标签的一部分，导致生成的HTML文档结构混乱，出现格式损坏。
• 当把说明文本放在标签下方时，Napoleon会先完整解析所有结构化标签，再将后续文本识别为补充描述，这符合它的解析优先级（结构化标签优先处理），所以文档显示正常。

解决办法 #

办法1：给描述文本和标签块添加空行 #

如果坚持使用reStructuredText风格标签，只需在说明文本和第一个:param之间加至少一个空行，明确分隔两个部分：

def calculate_sum(a, b):
    """计算两个数的和。

    :param a: 第一个加数
    :type a: int
    :param b: 第二个加数
    :type b: int
    :return: 两个数的和
    :rtype: int
    """
    return a + b

办法2：切换到Google/NumPy风格docstring #

Napoleon对Google/NumPy风格的兼容性更好，这类格式不需要严格的位置限制，写法更灵活：

def calculate_sum(a, b):
    """计算两个数的和。

    Args:
        a (int): 第一个加数
        b (int): 第二个加数

    Returns:
        int: 两个数的和
    """
    return a + b

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