如何避免Sphinx使用__slots__时重复显示类文档属性？

问题原因 #

当类定义了__slots__时，Sphinx的autodoc会从两个渠道提取属性信息：

• 类文档字符串（docstring）里的Attributes区块（由napoleon扩展解析）
• 自动扫描__slots__中的属性并生成无描述条目

两者叠加就造成了属性重复显示的问题。

解决方案 #

方案1：通过钩子过滤__slots__生成的无描述属性 #

在conf.py末尾添加以下代码，让autodoc跳过从__slots__生成的无文档属性，只保留类docstring中定义的带描述属性：

def skip_slots_attributes(app, what, name, obj, skip, options):
    # 跳过来自__slots__且无独立文档的属性
    if what == "class" and name in getattr(obj, "__slots__", ()):
        if name not in obj.__dict__:
            return True
    return skip

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

原理是利用autodoc-skip-member钩子，判断属性是否来自__slots__且没有独立文档，自动跳过这类属性的提取，避免和docstring中的条目重复。

方案2：关闭napoleon的属性解析（不推荐） #

如果愿意放弃docstring中的属性描述，可以修改napoleon配置，让它不再解析Attributes区块：

napoleon_include_attributes = False

此方法会丢失你在类docstring中编写的属性说明，仅保留__slots__生成的无描述属性，因此仅作为备选方案。

验证步骤 #

修改conf.py后，重新执行Sphinx构建命令：

sphinx-build -b html docs/source docs/build

查看生成的文档，类属性将只显示一次，且保留你在docstring中编写的描述内容。

内容的提问来源于stack exchange，提问作者Pablo Ariño