求助：Read the Docs构建部分.ipynb文档HTML页面空白问题排查

问题背景 #

我们使用Read the Docs结合Sphinx托管GitHub上的软件包文档，文档包含.ipynb格式的Python笔记本文件，这些文件会被渲染为HTML页面。近期遇到以下异常：

• Read the Docs构建任务显示成功，但部分.ipynb对应的HTML页面完全空白
• 调试日志中未发现相关报错，且部分内容相似的笔记本可正常渲染
• 本地构建文档时，所有笔记本的HTML渲染完全正常
• 原本构建成功的旧版本文档（如v0.9.0版本的audio_and_spectrogram.html）现在也变为空白，但网页存档显示其原本已成功渲染，推测是Read the Docs的平台变更引发该问题

排查步骤 #

1. 核对环境版本差异 #

• 对比Read the Docs构建日志中Python、Sphinx、nbsphinx（或其他.ipynb渲染依赖）的版本，和本地构建使用的版本是否一致
• 检查构建日志的依赖安装环节，确认是否有依赖被自动升级（比如Sphinx或nbsphinx的大版本更新）
• 在本地模拟Read the Docs的环境（安装相同版本的依赖），重新构建文档，验证是否能复现空白问题

2. 分析.ipynb文件的特殊性 #

• 对比正常渲染和空白页面对应的.ipynb文件，找出差异：比如是否包含特殊单元格（音频组件、复杂可视化、大尺寸输出内容）、是否存在隐性语法兼容问题（本地环境兼容但Read the Docs环境不兼容）
• 尝试简化空白页面的.ipynb文件（比如逐步删除部分单元格），提交到Read the Docs重新构建，定位引发问题的具体内容

3. 检查Read the Docs构建配置 #

• 确认readthedocs.yml配置文件是否正确，是否指定了固定的依赖版本，避免平台自动更新依赖
• 检查是否开启了Read the Docs的新特性（如虚拟环境隔离、缓存机制），尝试临时关闭这些特性进行测试
• 仔细梳理构建日志的所有内容，排查是否有被忽略的警告信息（可能不是明显的错误，而是隐性的兼容性提示）

4. 验证旧版本构建历史 #

• 查看旧版本（如v0.9.0）最初成功构建时的依赖版本，对比现在重新构建旧版本时的依赖版本，确认是否因依赖升级导致问题
• 在Read the Docs中重新触发旧版本的构建，查看实时日志，捕捉可能的隐性错误

解决思路 #

• 锁定依赖版本：在readthedocs.yml中明确指定Sphinx、nbsphinx及相关依赖的具体版本，和本地构建环境保持一致，避免平台自动更新依赖
• 修复.ipynb兼容性：如果定位到是特定单元格引发的问题，修改对应内容（比如替换不兼容的可视化代码、简化大输出内容）
• 调整平台环境：如果确认是Read the Docs的平台变更导致，联系平台支持团队反馈问题，或者通过配置指定使用旧版本的构建环境（如指定Ubuntu版本）
• 更换渲染工具：如果nbsphinx存在兼容性问题，尝试使用其他.ipynb渲染工具（如sphinx-book-theme、m2r2结合Jupyter转换）

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