如何为Pydantic类编写规范docstring并解决Sphinx属性重复展示问题

出现重复的核心原因是Sphinx默认会同时提取类docstring中的:param:字段，以及类定义中声明的静态属性，两类内容都会被渲染成参数/属性说明，导致重复。你提到的「忽略静态属性」的需求可以通过以下方式实现：

方案1：全局配置自动跳过Pydantic字段（推荐） #

直接在Sphinx项目的conf.py文件中添加钩子函数，自动识别并跳过Pydantic模型的字段属性，无需手动逐个配置：

def skip_pydantic_fields(app, what, name, obj, skip, options):
    # 匹配Pydantic字段，跳过渲染避免重复
    if what == "class" and hasattr(obj, "field_info"):
        return True
    return skip

def setup(app):
    app.connect("autodoc-skip-member", skip_pydantic_fields)

配置完成后重新生成文档即可，所有Pydantic模型的字段都不会被单独提取，只会保留类docstring中你写的参数说明。

方案2：单类手动指定忽略属性 #

如果只需要给少数类做适配，可以直接在rst文档的autoclass指令中添加排除规则：

.. autoclass:: your_module_name.Point
    :exclude-members: x, y

该方式需要手动列出所有要排除的字段，适合类数量少、字段变动频率低的场景。

拓展：更符合Pydantic规范的文档写法 #

如果你愿意调整docstring的写法，可以采用Pydantic官方推荐的方案，不在类docstring中写:param:说明，改为给字段添加Field描述：

from pydantic import BaseModel, Field

class Point(BaseModel):
    """
    Class to represent a point

    :Example:
    .. code-block:: python
        >>> p = Point(x=123, y=142)
    """
    x: int = Field(description="integer for x")
    y: int = Field(description="integer for y")

此时可以删掉上面的跳过配置，Sphinx会自动提取Field中的描述作为属性说明，不会出现重复问题，也更符合Pydantic的使用习惯。

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