Debian软件包构建报错：dh_sphinxdoc提示文件不在索引中求解决

报错原因分析 #

• 这是debhelper的dh_sphinxdoc工具校验Sphinx文档索引时触发的错误：当Sphinx生成的objects.inv索引文件中未记录1.0/jquery-3.5.1.js这个静态资源，但该文件实际存在于文档输出目录时，就会触发此校验失败。
• 常见触发场景：
  • Sphinx与debhelper版本不兼容，新旧版本对静态资源的索引生成逻辑存在差异
  • 自定义Sphinx主题/扩展引入了额外静态资源，但未正确触发索引更新
  • 构建过程中残留旧的索引缓存，与新生成的静态文件不匹配

具体解决措施 #

1. 强制重新生成Sphinx索引 #

先清理旧的文档构建产物与缓存，再重新生成文档，确保索引与静态资源完全同步：

# 清理旧的文档输出目录
rm -rf docs/_build
# 重新生成HTML文档，强制更新索引
sphinx-build -b html docs docs/_build/html

2. 跳过索引校验（临时规避） #

若确认该静态资源无需被索引，可在debian/rules中添加规则跳过dh_sphinxdoc的索引检查：

override_dh_sphinxdoc:
	dh_sphinxdoc --no-index-check

3. 对齐Sphinx与debhelper版本 #

优先使用Debian官方源适配的版本，避免pip安装的非兼容版本：

apt-get install --reinstall python3-sphinx debhelper

若使用自定义主题/扩展，需确认其与当前Sphinx版本的兼容性，必要时更新主题/扩展。

4. 清理Debian构建缓存 #

构建过程中的缓存可能导致索引不匹配，清理后重新构建包：

dh_clean
dpkg-buildpackage -rfakeroot -uc -us

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