如何在Sphinx中禁用内部类型的模块路径替换，保留源码注解？

我之前也被这个问题折腾过好一阵子！本来以为是小问题，结果找了半天才搞定——Sphinx默认确实会把类型注解里的内部类型自动展开成全模块路径，搞得文档里的类型写法和源代码完全不一样，可读性差很多。下面分享几个我亲测有效的解决方法：

1. 用autodoc_typehints_format（Sphinx 4.0+适用） #

这是最简单直接的方法，只要你的Sphinx版本够新（4.0及以上），在项目的conf.py里添加一行配置：

autodoc_typehints_format = 'short'

这个配置会让Sphinx自动使用类型的短名称，而不是展开成完整的模块路径。比如你代码里写的MyInternalType，文档里就会保留这个名字，不会变成my_module.MyInternalType。

2. 配置autodoc_type_aliases适配旧版本或特殊类型 #

如果你的Sphinx版本比较老，或者有些类型用上面的方法还是没生效，可以手动在conf.py里定义类型别名映射：

autodoc_type_aliases = {
    'MyInternalType': 'MyInternalType',
    'AnotherType': 'AnotherType'
}

把你想保留原始写法的类型名作为键和值填进去，Sphinx生成文档时就会用你指定的别名，而不是自动展开的模块路径。这个方法对相对导入的内部类型特别管用。

3. 手动在docstring里指定类型（个别场景） #

如果只是少数几个函数/类的类型注解有问题，不想改全局配置，可以直接在docstring里用:type:指令手动覆盖：

def process_data(data: MyInternalType) -> bool:
    """处理内部数据的函数

    :param data: 待处理的内部数据对象
    :type data: MyInternalType
    :return: 处理是否成功
    """
    # 函数逻辑...

这样Sphinx会优先使用你在docstring里指定的类型名，忽略自动生成的模块路径。

4. 借助第三方扩展sphinx-autodoc-typehints #

如果上面的方法都满足不了需求，可以试试这个专门处理类型注解的第三方扩展。首先安装它：

pip install sphinx-autodoc-typehints

然后在conf.py里把它加入扩展列表，并开启短名称模式：

extensions = [
    # 其他扩展...
    'sphinx_autodoc_typehints'
]

typehints_use_short_names = True

这个扩展对类型注解的处理比默认的autodoc更灵活，还支持很多高级配置，比如处理泛型、可选类型等场景。

试完这些方法，应该就能让你的文档里的类型注解和源代码保持一致了！

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