Sphinx Autodoc如何跳过空子模块及指定章节？

我之前也遇到过类似的情况，你之前的代码问题出在对autodoc-skip-member信号的what参数理解有误——what指代的是被处理对象的类型（比如module、class、function），而不是生成的章节名称（比如"Submodules"）。要跳过空的子模块，我们需要准确识别出没有可展示内容的子模块，然后告诉Sphinx跳过它们。

步骤1：识别并跳过空的子模块 #

我们可以借助inspect模块来检查子模块是否包含可展示的公共成员（类、函数、变量等），如果没有就跳过该子模块。在你的conf.py中添加以下代码：

import inspect

def skip_empty_submodules(app, what, name, obj, skip, options):
    # 只处理模块类型的对象
    if what == "module":
        # 检查模块是否有可展示的公共成员（非下划线开头的类/函数/变量）
        public_members = []
        for member_name, member in inspect.getmembers(obj):
            # 排除私有成员、内置属性和嵌套子模块
            if not member_name.startswith("_") and not inspect.ismodule(member):
                # 只保留可被autodoc渲染的类型：类、函数、变量
                if inspect.isclass(member) or inspect.isfunction(member) or not inspect.ismethod(member):
                    public_members.append(member_name)
        
        # 如果没有公共成员，且模块本身没有文档字符串，就跳过
        if not public_members and not obj.__doc__:
            return True
    # 其他情况保持原有跳过逻辑
    return skip

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

步骤2：调整判断逻辑适配需求 #

上面的判断逻辑是：子模块既没有公共成员，也没有自身的文档字符串时才跳过。如果你想保留有文档字符串的空模块，只需要移除and not obj.__doc__这部分即可。

为什么之前的代码不生效？ #

你之前写的if what == "Submodules"完全不对，因为what参数的取值范围是固定的几种对象类型，比如：

• module: 处理模块时
• class: 处理类时
• function: 处理函数时
• method: 处理类方法时

"Submodules"是Sphinx自动生成的章节标题，当某个模块有子模块被保留时才会显示。如果所有子模块都被我们的逻辑跳过了，这个章节标题自然就不会出现在最终的文档里了。

额外提示：处理残留的"Submodules"标题 #

如果某些父模块下所有子模块都被跳过，但"Submodules"标题还在，可以尝试调整autodoc_default_options中的members配置，或者检查是否有子模块被间接导入未被过滤。不过这种情况很少见——只要所有子模块都被正确跳过，Sphinx就不会生成这个章节。

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