如何为特定Python类关闭sphinx-apidoc的:undoc-members:选项？

问题场景 #

我遇到了GitHub issue #8664中的问题：Python类Foo同时包含类型注解成员与Google风格Attributes文档，示例代码如下：

class Foo(Bar):
    """Something something.

    Attributes:
         baz: A handy thing.
    """

    baz: str

运行sphinx-apidoc时触发报错：

docstring of my_project.Foo.baz:1:duplicate object description of my_project.Foo.baz, other instance in source/my_project, use :noindex: for one of them

排查后确认，问题源于sphinx-apidoc默认自动设置了:undoc-members:选项——该选项会自动提取类中未手动文档化的成员，但我的baz已经在类文档的Attributes块中做了说明，加上类型注解后被重复识别，引发冲突。需求是仅为Foo类关闭:undoc-members:选项，不影响其他类的自动文档生成。

解决方案 #

方法1：直接修改生成的rst文件 #

找到sphinx-apidoc生成的对应类rst文件，在autoclass指令中移除:undoc-members:选项：
原生成代码：

.. autoclass:: my_project.Foo
   :members:
   :undoc-members:

修改后：

.. autoclass:: my_project.Foo
   :members:

如果担心后续sphinx-apidoc重新生成覆盖修改，可以添加--no-overwrite参数执行生成，或者将修改后的rst文件移出自动生成目录，改为手动维护。

方法2：通过Sphinx事件钩子动态修改选项 #

在项目的conf.py中添加事件处理逻辑，针对特定类动态移除:undoc-members:选项：

def autodoc_process_options(app, name, obj, options):
    # 匹配目标类的完整限定名
    if name == 'my_project.Foo':
        # 移除undoc-members选项，仅对当前类生效
        options.pop('undoc-members', None)

def setup(app):
    app.connect('autodoc-process-options', autodoc_process_options)

这个钩子会在autodoc处理每个对象的配置选项时触发，匹配到my_project.Foo时自动移除:undoc-members:，其他类不受影响。

方法3：跳过重复成员避免冲突 #

如果不想完全关闭:undoc-members:，可以通过autodoc-skip-member事件跳过重复的baz成员：

def autodoc_skip_member(app, what, name, obj, skip, options):
    # 仅跳过Foo类的baz成员的自动文档提取
    if what == 'class' and name == 'baz' and obj.__qualname__ == 'Foo.baz':
        return True
    return skip

def setup(app):
    app.connect('autodoc-skip-member', autodoc_skip_member)

这样baz只会使用类文档中Attributes块的说明，不会被类型注解重复生成文档，同时保留其他类的:undoc-members:功能。

内容的提问来源于stack exchange，提问作者J. Lerman