为何Sphinx+autodoc无法展开PEP 695风格类型别名？

问题概述 #

使用PEP 695定义的type Hello = str风格类型别名时，Sphinx配合autodoc、autosummary、intersphinx工具会出现两个问题：

• 无法生成指向别名目标类型的内部文档链接
• autodoc无法自动展开别名的实际类型信息
  此前针对PEP 484风格Hello: TypeAlias = str的配置方案已完全失效，尽管社区讨论明确该语法应被支持，但当前工具版本仍未解决此问题。

临时解决方案 #

1. 手动在RST文件中声明类型别名

直接在文档的.rst文件中使用autodata指令强制指定别名的类型信息，确保autodoc能识别并生成正确的文档：

.. autodata:: your_module.Hello
   :annotation: = str

如果目标类型（如str）已被intersphinx索引或属于项目内部类型，这种方式可以生成对应的文档链接。

2. 自定义Autodoc处理函数

在Sphinx配置文件conf.py中添加自定义处理逻辑，识别PEP 695类型别名并补充文档信息：

from sphinx.ext.autodoc import DataDocumenter

def setup(app):
    def process_pep695_type_aliases(docobj, lines):
        # 检测是否为PEP 695类型别名（Python 3.12+）
        if hasattr(docobj, "__supertype__") and not hasattr(docobj, "__annotations__"):
            target_type = docobj.__supertype__
            # 添加类型说明和链接
            lines.append(f"**类型别名指向**: :class:`{target_type.__module__}.{target_type.__name__}`")
    
    app.connect("autodoc-process-docstring", process_pep695_type_aliases)

注意：__supertype__是CPython 3.12为PEP 695类型别名新增的属性，不同Python实现或版本可能存在差异。

3. 双风格兼容定义

临时同时保留PEP 484和PEP 695风格的类型别名定义，让旧的autodoc配置继续生效：

from typing import TypeAlias

# PEP 695风格定义
type Hello = str
# 补充PEP 484风格注解，供autodoc识别
Hello: TypeAlias = Hello

环境验证 #

问题通常出现在以下版本组合中：

• Python 3.12+（使用PEP 695语法）
• Sphinx 7.x 系列
• sphinx-autodoc-typehints 2.x 系列

后续建议 #

目前官方尚未完全实现对PEP 695类型别名的完整支持，需等待Sphinx或相关扩展的版本更新。在此之前，可使用上述临时方案维持文档的完整性。

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