使用Sphinx为含Annotated[]字段的Python数据类生成文档遇问题

问题背景 #

使用Sphinx的autodoc_typehints（或sphinx_autodoc_typehints包）为Python数据类字段生成文档时，采用Annotated[int, Doc("hi")]方式添加字段说明，配合以下配置和指令：

数据类代码：

from dataclasses import dataclass
from typing import Annotated
from typing_extensions import Doc

@dataclass
class Tester:
    """Test"""
    x: Annotated[int, Doc("hi")] = 1

Sphinx autoclass指令：

.. autoclass:: config.Tester
   :members:
   :undoc-members:
   :exclude-members: __init__, __post_init__, __dataclass_fields__, __dataclass_self__, __dataclass_params__
   :member-order: bysource

conf.py配置：

autodoc_typehints = "description"
set_typehints_format = "short"

出现类型注释显示异常、内容重复的问题，需要实现：

• 正常生成类型注释文档
• 内容仅显示一次
• 保留以编程方式访问字段文档字符串的能力，避免使用PEP 224风格的成员文档字符串

解决方案 #

1. 切换到sphinx_autodoc_typehints扩展 #

原生Sphinx的autodoc_typehints对数据类Annotated字段的支持存在局限性，改用专门的sphinx_autodoc_typehints包能更好处理这类场景：

首先安装扩展：

pip install sphinx-autodoc-typehints

然后在conf.py中启用扩展并调整配置：

extensions = [
    # 保留其他必要扩展（如sphinx.ext.autodoc）
    'sphinx.ext.autodoc',
    'sphinx_autodoc_typehints',
]

# 核心配置
autodoc_typehints = "description"
typehints_format = "short"
# 控制默认值显示格式，避免重复内容
typehints_defaults = "comma"
# 可选：禁用类型提示在签名中重复显示
typehints_signature = False

2. 优化autoclass指令参数 #

移除:undoc-members:选项，因为字段的文档已经通过Annotated[..., Doc(...)]定义，该选项会导致无独立文档字符串的成员被重复渲染：

.. autoclass:: config.Tester
   :members:
   :exclude-members: __init__, __post_init__, __dataclass_fields__, __dataclass_self__, __dataclass_params__
   :member-order: bysource

3. 保留编程访问文档字符串的能力 #

通过dataclasses.fields和typing模块的工具函数，可以直接提取Annotated中的Doc内容，无需依赖PEP 224风格的文档字符串：

from dataclasses import fields
from typing import get_args, get_origin
from typing_extensions import Doc

def get_field_doc(dataclass_cls, field_name):
    for field in fields(dataclass_cls):
        if field.name == field_name:
            annot_type = field.type
            if get_origin(annot_type) is Annotated:
                # 提取Annotated中的Doc实例
                doc_arg = next(arg for arg in get_args(annot_type) if isinstance(arg, Doc))
                return doc_arg.__args__[0]
    return None

# 使用示例
print(get_field_doc(Tester, "x"))  # 输出: hi

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