Sphinx结合Pydantic使用自定义类型提示的文档生成问题

问题 #

使用Sphinx结合apidoc和autodoc-pydantic扩展生成Python项目文档时，当Pydantic的BaseModel子类中，类变量的类型提示为未继承BaseModel的普通类时，文档生成会失败；但使用继承BaseModel的类作为类型提示时则正常。

最小可复现示例 #

代码文件

from pydantic import BaseModel

class MyClassOne(BaseModel):
    r"""
    用作类型提示测试，继承自BaseModel。
    """


class MyClassTwo:
    r"""
    另一个用作类型提示的类，未继承BaseModel。
    """


class MyClassThree(BaseModel):
    r"""
    使用其他类作为类型。
    """

    var_1: MyClassOne = None  #: 使用继承BaseModel的类型提示
    # var_2: MyClassTwo = None  #: 使用未继承BaseModel的类型提示

Sphinx配置文件conf.py

import os
import sys

sys.path.insert(0, os.path.abspath(".."))
sys.setrecursionlimit(1500)

project = "Demo Sphinx/Pydantic bug"
copyright = "2023,"
author = "N/A"
release = "1.0.0"

extensions = [
    "sphinx.ext.autodoc",
    "sphinxcontrib.apidoc",
    "sphinxcontrib.autodoc_pydantic",
]

templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
html_theme = "sphinx_rtd_theme"
autodoc_pydantic_model_show_json = False

取消注释var_2后，文档生成流程会报错失败，需要找到允许任意类作为类型提示的解决办法。

解决方案 #

这是autodoc-pydantic的默认行为导致的——它默认会尝试解析类型提示中的Pydantic模型并生成额外文档内容，但遇到普通类时会出错。可以通过修改conf.py的扩展配置，关闭针对非Pydantic模型的强制解析：

修改conf.py添加配置项 #

直接禁用字段类型的自动解析，仅保留原始类型提示文本：

# 关键配置：关闭对字段类型的特殊解析，避免非Pydantic类触发错误
autodoc_pydantic_field_type_show = False

# 可选：关闭其他不需要的Pydantic字段额外文档生成
autodoc_pydantic_field_show_alias = False
autodoc_pydantic_field_show_required = False
autodoc_pydantic_field_validator_show = False

也可以用字典形式统一配置：

autodoc_pydantic_field = {
    "type_show": False,
    "alias_show": False,
    "required_show": False,
    "validator_show": False,
}

补充说明 #

• autodoc_pydantic_field_type_show默认值为True，开启时扩展会尝试将类型提示中的类解析为Pydantic模型并生成关联文档，设置为False后会直接保留原始类型提示文本，避免解析非Pydantic类时出错。
• 另外可以确保普通类MyClassTwo被Sphinx正确识别：比如在文档中显式导入该类，或在conf.py中添加autodoc_default_options = {"members": True}，确保所有类成员被文档化，避免Sphinx无法找到类定义。

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