Sphinx autosummary生成Python包深度文档异常问题求助

核心问题 #

为Python包va_sdk生成带可点击类链接的深度文档时，必须通过「重命名autosummary模板目录→构建→恢复目录→再次构建」的两步流程才能成功，直接使用模板目录反而无法生成深度文档。

可能原因及排查步骤 #

1. Sphinx缓存干扰 #

Sphinx会缓存构建过程中的模板、文档树等数据，当自定义autosummary模板存在时，旧缓存可能导致模板未正确加载。

• 每次构建前彻底清理缓存：
  • Windows：执行 rmdir /s /q _build，删除项目根目录下的.doctree文件
  • 类Unix：执行 rm -rf _build .doctree
• 清理后直接执行 ./make.bat html，看是否能正常生成带深层链接的文档。

2. 自定义模板依赖初始构建产物 #

你的autosummary自定义模板可能依赖默认模板生成的基础文档结构（比如模块索引、类的stub文档），第一次用默认模板构建后才生成了这些必要文件，第二次自定义模板才能解析并生成深层链接。

• 检查_templates/autosummary下的模板文件，看是否有引用{{ fullname }}或其他需要先存在的文档节点的逻辑，确认模板是否需要先有基础文档结构才能正常渲染。

3. 自定义模板存在逻辑问题 #

直接使用自定义模板时，模板内的错误逻辑可能阻塞了深度文档的生成，而默认模板先完成了文档节点的初始化，第二次构建时模板能正常工作。

• 对比默认autosummary模板（可从Sphinx安装目录找到）和你的自定义模板，检查是否有语法错误、变量引用错误，比如是否遗漏了生成链接的关键代码段。

4. 构建日志分析 #

通过 verbose 模式查看构建过程，定位差异：

• 执行 ./make.bat html -v，分别记录「直接用自定义模板构建」和「两步法构建」的日志
• 对比日志中autosummary相关的生成步骤，看第一次无模板时生成了哪些文件，第二次有模板时哪些步骤触发了深层链接的生成。

验证建议 #

先尝试清理缓存后直接构建，如果问题解决，说明是缓存导致的；如果不行，再检查模板内容和构建日志，定位模板或配置的问题。

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