使用Sphinx autosummary递归生成API文档遇模板问题求助

我来帮你一步步排查修复遇到的两个核心问题：模板不被识别，以及模板内{% if classes %}和{% if functions %}指令未执行的情况。

一、先解决模板不生效的问题 #

你提到删除docs/_autosummary后模板终于生效，这是因为Sphinx autosummary默认会优先复用已经生成的静态文件，而不是重新渲染模板。所以每次修改模板后，必须清理旧的生成文件，否则Sphinx会直接跳过模板渲染步骤。

推荐两种清理方式：

• 手动删除docs/_autosummary和docs/_build文件夹（彻底清除缓存）
• 执行构建命令时添加强制刷新参数：sphinx-build -b html docs docs/_build/html -E（-E参数会强制重新生成所有文档，忽略缓存）

二、修复条件指令未执行的问题 #

你的模板和配置里有两个关键错误，导致类和函数列表无法渲染：

1. 指令语法错误 #

模板里的autosummary指令少了末尾的冒号！你写的是.. autosummary:，正确语法应该是.. autosummary::（两个冒号）。这个小错误会让Sphinx完全无法识别指令，自然不会处理后续的类/函数循环。

2. 缺少递归生成的配置 #

要让autosummary递归生成子模块、类、方法的独立页面，必须在conf.py中添加以下配置：

# 在docs/conf.py中添加
autosummary_generate = True
autosummary_generate_overwrite = True

• autosummary_generate：开启自动生成未手动编写的文档页面
• autosummary_generate_overwrite：允许覆盖已生成的文件，确保模板修改能生效

另外，如果你需要递归生成sparse下所有子模块的文档，还要在modules.rst的autosummary指令中添加:recursive:选项：

# modules.rst修改后内容
API Reference
=============

Modules
-------

.. autosummary::
   :toctree: _autosummary
   :recursive:

   sparse

修正后的模板文件_templates/autosummary/module.rst #

把指令的冒号补全，确保语法正确：

{{ fullname | escape | underline }}

Description
-----------

.. automodule:: {{ fullname | escape }}

{% if classes %}
Classes
-------

.. autosummary::
   :toctree: _autosummary

{% for class in classes %}
   {{ class }}
{% endfor %}
{% endif %}

{% if functions %}
Functions
---------

.. autosummary::
   :toctree: _autosummary

{% for function in functions %}
   {{ function }}
{% endfor %}
{% endif %}

三、完整的构建流程 #

最后按照以下步骤重新构建，确保所有修改生效：

1. 删除docs/_autosummary和docs/_build目录（彻底清理缓存）
2. 执行构建命令：sphinx-build -b html docs docs/_build/html
3. 打开docs/_build/html/index.html查看生成的文档

这样就能让模板正常识别，并且正确渲染类和函数列表，递归生成所有API的独立页面了。

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