Sphinx配置：隐藏__init__.py导入模块 让函数归属上层模块

默认配置下两个逻辑导致显示不符合预期：

• autosummary的:recursive:参数会遍历包下所有子模块，包括下划线开头的私有子模块，为这些私有模块单独生成文档节点
• autodoc默认按照代码定义的原始位置归属对象，不会因为对象被导入到其他模块就修改其所属模块的显示

按以下顺序调整即可实现需求：

• 第一步：修改Sphinx配置文件conf.py，添加跳过私有模块、修正对象归属的配置

# conf.py 新增/修改以下配置
autodoc_default_options = {
    'members': True,
    'undoc-members': True,
    'show-inheritance': True,
    # 关闭私有成员、特殊成员扫描
    'private-members': False,
    'special-members': False,
}
# 关闭模块名前缀显示，避免对象名带原始子模块路径
add_module_names = False

# 注册钩子跳过所有下划线开头的私有子模块
def skip_private_modules(app, what, name, obj, skip, options):
    if what == "module" and name.startswith("_"):
        return True
    return skip

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

• 第二步：在module2/__init__.py中显式声明__all__列表，明确对外公开的成员范围
  在已有的导入语句后追加__all__声明，把所有需要对外暴露、显示在module2文档下的函数、类名全部列入：

# mymodule/module2/__init__.py
from mymodule.module2._hiden_submodule1 import *
from mymodule.module2._hiden_submodule2 import *
from mymodule.module2._hiden_submodule3 import *

# 显式声明模块公开成员
__all__ = [
    # 填入所有从隐藏子模块导入的、需要展示的成员名，示例：
    # "public_func1",
    # "PublicClass1",
]

• 第三步：修改自定义模板custom-module-template.rst，过滤私有子模块的递归生成
  在模板遍历子模块的逻辑中增加判断，跳过所有名称以下划线开头的子模块，核心片段参考：

{# 模块成员渲染部分 #}
{% if members %}
.. rubric:: 模块成员
.. autosummary::
   :toctree:
   {% for item in members %}
   {% if not item.startswith('_') %}
   ~{{ fullname }}.{{ item }}
   {% endif %}
   {% endfor %}
{% endif %}

{# 子模块渲染部分 #}
{% if submodules %}
.. rubric:: 子模块
.. autosummary::
   :toctree:
   :template: custom-module-template.rst
   {% for submodule in submodules %}
   {# 过滤所有私有子模块 #}
   {% if not submodule.split('.')[-1].startswith('_') %}
   {{ submodule }}
   {% endif %}
   {% endfor %}
{% endif %}

注意：重新生成文档前，先删除之前生成的_autosummary缓存目录和build输出目录，避免旧缓存导致配置不生效，清理后再执行文档构建命令即可。

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