使用Jinja2配合Sphinx autosummary无法生成存根文件问题

我之前也遇到过一模一样的问题——用Jinja2动态渲染autosummary条目时，Sphinx根本不生成对应的存根文件，手动加的条目却正常。核心原因其实很简单：Sphinx的autosummary_generate默认是在Jinja2渲染.rst文件之前扫描内容的，它看不到动态生成的那些条目，自然不会去生成存根。

下面是我亲测有效的解决方案，完全适配你需要通过conf.py动态生成条目列表的需求：

步骤1：在conf.py中动态收集目标条目 #

首先，在你的conf.py里，先把需要生成文档的类的完整导入路径收集起来。比如你提到的这三个类：

# conf.py
from Package.SubModule import classA, classB, classD

# 生成完整的模块路径（必须用这种全路径，autosummary才能识别）
autosummary_targets = [
    "Package.SubModule.classA",
    "Package.SubModule.classB",
    "Package.SubModule.classD",
]

# 把这个列表传给Jinja2模板，方便在.rst里循环
html_context = {
    "autosummary_classes": autosummary_targets,
}

步骤2：手动触发autosummary存根生成 #

既然Sphinx自动扫描看不到动态条目，我们就直接调用autosummary的生成函数，提前把存根造出来。在conf.py里添加一个setup函数，绑定到Sphinx的构建初始化事件：

# conf.py 继续添加
from sphinx.ext.autosummary.generate import generate_autosummary_docs

def setup(app):
    # 在文档构建开始前，手动生成存根
    def generate_stubs(_):
        # 存根文件的输出目录，要和你.rst里toctree指定的一致
        output_dir = f"{app.srcdir}/_autosummary"
        # 调用autosummary的生成函数
        generate_autosummary_docs(
            autosummary_targets,
            output_dir=output_dir,
            app=app,
            overwrite=True,  # 每次构建都覆盖旧存根，避免缓存问题
        )
    # 绑定到builder-inited事件，确保在渲染前执行
    app.connect('builder-inited', generate_stubs)

步骤3：在.rst模板中用Jinja2渲染autosummary块 #

现在你的.rst模板可以放心地用Jinja循环了，比如：

{{ fullname | escape | underline}}

.. autosummary::
   :toctree: _autosummary
   :template: class.rst  # 如果你有自定义的类模板，没有可以去掉

   {% for cls in autosummary_classes %}
   {{ cls }}
   {% endfor %}

关键配置检查 #

最后确认你的conf.py里这些配置都到位：

• extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']（两个扩展都要加）
• autosummary_generate = True（虽然我们手动生成了，保留这个也不冲突，还能处理手动添加的条目）
• autosummary_imported_members = True（如果需要生成类的成员方法文档，可选）

为什么手动添加的条目能正常工作？因为Sphinx在启动时会先扫描所有.rst文件里的autosummary块，收集静态写死的条目，然后生成存根。但Jinja2渲染是在扫描之后才进行的，动态生成的条目根本没被Sphinx看到，所以不会生成存根。我们上面的方法就是绕开自动扫描，直接告诉autosummary要生成哪些存根，完美解决动态条目的问题。

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