Sphinx自动文档中如何支持管道格式的类型提示？

问题原因 #

Sphinx默认的类型解析逻辑对Python 3.10引入的PEP 604联合类型语法（X | None）以及泛型元组写法（tuple[Type1, Type2]）支持不足，而旧版的Optional[UGrid3d]属于传统typing模块语法，能被正常解析。

解决方案 #

1. 升级依赖版本 #

• 确保Python版本≥3.10：PEP 604的|语法是Python 3.10原生支持的，若使用更低版本，需安装typing_extensions包（pip install typing-extensions），让Sphinx能识别扩展类型定义。
• 升级Sphinx到最新稳定版：执行pip install --upgrade sphinx，较新版本的Sphinx对现代类型提示语法兼容性更好。
• 安装sphinx-autodoc-typehints扩展：这是专门优化类型提示解析的工具，能完美支持|联合类型和泛型元组写法，执行pip install sphinx-autodoc-typehints完成安装。

2. 配置Sphinx的conf.py #

在项目的docs/conf.py中修改以下配置：

# 启用必要的扩展
extensions = [
    'sphinx.ext.autodoc',
    'sphinx_autodoc_typehints',
    # 若使用Google/Numpy风格的docstring，可添加'sphinx.ext.napoleon'
    # 'sphinx.ext.napoleon',
]

# 类型提示相关配置
# 启用类型检查模式，提升联合类型解析准确性
set_type_checking_flag = True
# 若Python版本<3.10，开启此选项以使用typing_extensions解析类型
# typehints_use_typing_extensions = True
# 设置类型提示显示位置（可选，'signature'显示在函数签名，'description'显示在文档描述）
autodoc_typehints = 'signature'

3. 验证效果 #

重新生成文档：

cd docs
make html

此时Sphinx应该能正常解析tuple[UGrid3d | None, UGrid3d | None]这类类型提示，不再抛出TypeError。

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