如何在Sphinx与ReStructuredText中实现跨文档图片链接至标题？

核心原因 #

跨文档引用标签时Sphinx无法识别ex_1，通常是目标文档未被纳入构建范围，或是引用语法不符合跨文档规范导致的。

具体解决步骤 #

1. 确保目标文档被Sphinx构建流程包含
   检查项目主文档（如index.rst）中的toctree指令，确认A.rst已被添加。只有被toctree包含的文档，其内部定义的标签才会被Sphinx收集并允许其他文档引用。
   示例index.rst中的toctree配置：

   .. toctree::
      :maxdepth: 2
      :caption: 文档目录
   
      A
      B
   

2. 修正跨文档图片链接的语法
   同文档内直接用标签名_的语法在跨文档场景下不生效，可改用以下两种正确方式：

   • 方式一：给image指令添加:target:选项，直接指向目标标签（需确保A.rst已被包含）

     .. image:: path/to/your/eximg01.png
        :target: ex_1
        :alt: Example Image 01
     

   • 方式二：使用ref角色包裹图片，明确指定跨文档标签

     .. ref:: ex_1
     
        .. image:: path/to/your/eximg01.png
           :alt: Example Image 01
     

3. 验证标签定义的正确性
   确认A.rst中的标签定义位置正确，标签必须放在目标标题的正上方（可允许空行，但不能被其他内容隔开）：

   .. _ex_1:
   
   Example 1
   ---------
   

4. 清理并重新构建文档
   执行以下命令清理旧构建缓存，避免缓存导致的标签识别问题：

   make clean
   make html
   

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