Sphinx中autofunction指令无法加载重载函数文档字符串问题

默认情况下，Sphinx的autofunction指令只会提取函数实现体的文档，不会自动展示每个@overload装饰的函数的文档字符串。要实现每个重载原型下方显示对应文档，按以下步骤操作：

1. 确保Python代码中@overload函数的文档字符串正确编写 #

每个@overload装饰的函数都要单独写好文档字符串，示例代码如下：

from typing import overload

@overload
def add_object(obj: str) -> bool:
    """将字符串类型对象添加到框架中。
    
    参数:
        obj: 要添加的字符串对象
    返回:
        添加成功返回True，失败返回False
    """
    ...

@overload
def add_object(obj: int, priority: int = 1) -> bool:
    """将整数类型对象添加到框架中，可指定优先级。
    
    参数:
        obj: 要添加的整数对象
        priority: 可选，添加优先级，默认1
    返回:
        添加成功返回True，失败返回False
    """
    ...

def add_object(obj, priority=None):
    # 实际实现代码
    if isinstance(obj, str):
        return True
    elif isinstance(obj, int):
        return True
    return False

2. 修改Sphinx配置文件conf.py #

在conf.py中确保启用sphinx.ext.autodoc扩展，并开启overloads选项：

# 已有的扩展列表中加入sphinx.ext.autodoc（如果没加的话）
extensions = [
    'sphinx.ext.autodoc',
    # 其他你用到的扩展...
]

# 设置autodoc默认选项，关键是开启overloads
autodoc_default_options = {
    'overloads': True,
    # 其他可选配置，比如members、show-inheritance等
}

3. 重新构建文档 #

执行Sphinx的构建命令（比如make html），重新生成文档后，framework.add_object的每个重载原型下方就会显示对应的文档字符串了。

如果你的Sphinx版本较旧（低于3.0），可能不支持overloads选项，建议升级到最新稳定版。

内容的提问来源于stack exchange，提问作者David Hožič