如何解决Sphinx跨LaTeX手册交叉引用的PDF显示异常问题？

问题背景 #

我有一个Sphinx文档项目，包含分属不同子目录的《开发者手册》和《参考手册》：

• HTML输出：合并为一套文档，跨手册:ref:引用正常工作
• LaTeX PDF输出：各自生成独立手册，手册内引用正常，但跨手册引用会显示目标名称（如model_section）而非标题文本，且无有效链接

需求：

请参阅《开发者手册》中的Models章节了解更多细节。
要求:ref:无需显式指定文本，PDF中至少显示对应标题，最好支持可点击链接。

解决方案 #

1. 用sphinx.ext.intersphinx实现跨文档引用（推荐） #

在conf.py中配置intersphinx，指向开发者手册的Sphinx生成的objects.inv文件：

intersphinx_mapping = {
    'dev_manual': ('../dev_manual/_build/html/', None),  # 开发者手册HTML构建目录
}

然后在参考手册中使用带前缀的:ref:引用：

请参阅 :ref:`dev_manual:dev_manual` 中的 :ref:`dev_manual:model_section` 章节了解更多细节。

• HTML输出：自动跳转对应页面，无需额外处理
• LaTeX输出：在conf.py中添加以下配置，确保intersphinx生成PDF兼容的引用：

  intersphinx_disabled_reftypes = []  # 不禁用任何引用类型
  

  需先构建开发者手册的HTML项目生成objects.inv，再构建参考手册。两个PDF放在同一目录时，会自动显示标题文本，点击可跳转到对应手册的锚点位置。

2. 用extlinks扩展分格式处理 #

在conf.py中配置extlinks，为不同输出格式定义路径：

extlinks = {
    'dev_html': ('../dev_manual/%s.html', '%s'),  # HTML跳转路径
    'dev_pdf': ('dev_manual.pdf#%s', '%s')        # PDF锚点路径
}

然后用only指令区分输出格式：

.. only:: html
    请参阅 :dev_html:`dev_manual` 中的 :dev_html:`model_section` 章节了解更多细节。

.. only:: latex
    请参阅 :dev_pdf:`《开发者手册》` 中的 :dev_pdf:`Models` 章节了解更多细节。

这种方式可确保PDF显示正确文本，若两个PDF同目录，点击能跳转对应锚点。

3. 手动定义文本回退（无扩展依赖） #

先统一定义替换变量：

.. |dev_manual| replace:: 《开发者手册》
.. |model_section| replace:: **Models**

再结合only指令区分格式：

.. only:: html
    请参阅 :ref:`dev_manual <dev_manual>` 中的 :ref:`model_section <model_section>` 章节了解更多细节。

.. only:: latex
    请参阅 |dev_manual| 中的 |model_section| 章节了解更多细节。

此方法至少保证PDF显示正确文本，HTML保留链接功能。

关键注意事项 #

• 两个手册需使用相同版本的Sphinx，避免环境差异导致引用失败
• LaTeX生成PDF时，Sphinx默认启用hyperref包，确保链接可点击
• 使用intersphinx时，必须先完成开发者手册的HTML构建，生成objects.inv文件

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