sphinxcontrib-bibtex与sphinx-multiversion文档引用异常问题

问题现象 #

使用sphinxcontrib-bibtex和sphinx-multiversion构建项目文档时：

• rst文件中使用:cite:引用bibtex键，sphinx-build和sphinx-multiversion均能正常识别；
• Python文档字符串中使用同一:cite:语法，仅sphinx-build可正常解析，sphinx-multiversion会提示找不到对应bibtex键（即使该键存在于配置的literature.bib文件中）。

可能的解决方案 #

1. 修正bib文件的路径配置 #

sphinx-multiversion构建不同分支时会切换工作目录，导致相对路径解析和sphinx-build不一致。在conf.py中使用绝对路径指定bib文件：

import pathlib

# 基于配置文件所在目录生成项目根路径
project_root = pathlib.Path(__file__).parent.parent
bibtex_bibfiles = [str(project_root / "literature.bib")]

2. 清除bibtex缓存 #

sphinx-multiversion的缓存机制可能导致bib文件未被重新加载，在conf.py中添加构建钩子强制刷新缓存：

def setup(app):
    # 每个版本构建前清除bibtex缓存
    app.connect('builder-inited', lambda app: app.env.bibtex_cache.clear())

3. 验证分支间bib文件一致性 #

确认目标构建分支的literature.bib中确实包含报错的引用键，避免分支间文件差异引发问题。

4. 调整扩展加载顺序 #

在conf.py的extensions列表中，将sphinxcontrib.bibtex放在sphinx_multiversion之前，确保bibtex扩展先完成初始化：

extensions = [
    'sphinxcontrib.bibtex',
    'sphinx_multiversion',
    # 其他扩展...
]

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