Sphinx保留automethod指令且无警告展示所有__init__方法的方案

核心问题拆解 #

问题出在skip_member的判断逻辑未区分自动生成的类成员文档和手动通过.. automethod::指定的文档，而skip_member的what参数返回class是正常行为——这个钩子是在遍历类的成员时触发的，what指代的是当前处理的父对象类型（即类），而非成员本身。

具体解决方案 #

方案1：修改skip_member函数，区分上下文场景 #

在项目的conf.py中调整skip_member的逻辑，通过检查调用栈判断是否处于手动automethod指令的上下文，从而避免重复生成：

import inspect
from sphinx.util.docutils import SphinxDirective

def skip_member(app, what, name, obj, skip, options):
    if skip:
        return True
    # 仅处理__init__方法的情况
    if name == "__init__":
        automethod_context = False
        frame = inspect.currentframe()
        try:
            # 向上追溯栈帧，确认是否是手动调用automethod指令
            while frame:
                if 'self' in frame.f_locals:
                    self_obj = frame.f_locals['self']
                    if isinstance(self_obj, SphinxDirective) and self_obj.name == 'automethod':
                        automethod_context = True
                        break
                frame = frame.f_back
        finally:
            del frame
        
        # 如果是手动指定的automethod，跳过自动生成（避免重复）
        if automethod_context:
            return True
        # 否则保留自动生成的__init__文档
        return False
    # 其他成员按默认逻辑处理
    return skip

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

方案2：自定义MethodDocumenter（进阶稳定版） #

如果栈帧检查的稳定性不足，可以直接重写MethodDocumenter，让它在处理__init__时自动检测是否已有手动指定的文档：

import inspect
from sphinx.ext.autodoc import MethodDocumenter
from docutils.parsers.rst.states import Body

class CustomMethodDocumenter(MethodDocumenter):
    def generate(self, *args, **kwargs):
        if self.object_name == "__init__":
            automethod_found = False
            frame = inspect.currentframe()
            try:
                # 检查当前文档上下文是否已有对应automethod指令
                while frame:
                    if 'state' in frame.f_locals:
                        state = frame.f_locals['state']
                        if isinstance(state, Body):
                            for node in state.memo.current_node.children:
                                if hasattr(node, 'rawsource') and f'automethod:: {self.fullname}' in node.rawsource:
                                    automethod_found = True
                                    break
                            if automethod_found:
                                break
                    frame = frame.f_back
            finally:
                del frame
            # 已有手动指定的文档，跳过自动生成
            if automethod_found:
                return
        # 其他情况按原逻辑生成文档
        super().generate(*args, **kwargs)

def setup(app):
    app.add_autodocumenter(CustomMethodDocumenter, override=True)

效果说明 #

两种方案都能：

• 保留手动添加的.. automethod::指令
• 避免__init__方法文档重复显示
• 消除重复描述的警告
• 正常生成所有类的__init__方法文档

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