如何使用 Sphinx 和 ReStructuredText 将图像链接到不同文档中的标题？

Question

我有一个用 Sphinx/rst 编写的文档，我想要一个链接到不同文件中标题的图像。

不知何故，以下不起作用，我不知道为什么：

在文档中

A.rst

我有以下标题：

.. _ex_1:

Example 1
---------

在文档

B.rst

中，我嵌入了图像并将目标设置为

ex_1

，如下所示：

.. |eximg01| image:: _static/ex_1.png
   :target: `ex_1`_

不幸的是，这不起作用并退出并出现以下错误：

ERROR: Unknown target name: "ex_1".

有人知道我该如何解决这个问题吗？
（像这样将图像嵌入到文档中

A.rst

就可以了）。

Answer 1

这与旧版 issue #4351 中描述的 Sphinx 限制相同。尽管在问题中您使用的是 替换定义 而不是

.. image:

指令，但在这两种情况下，问题是

:target:

选项不接受 内部超链接目标。

这似乎是 Sphinx 没有完美实现 reStructuredText 规范的少数情况之一，因为涉及的所有元素都是 reST 标记规范的一部分，并且它不仅清楚地说明了等效的

.. image::

指令，即

 :target

选项应该接受内部超链接目标，但它也给出了确切的示例：

目标：URI 或参考名称

使图像成为超链接引用（“可点击”）。选项参数可以是 URI（相对或绝对），或带下划线后缀的引用名称（例如

a name

_）。

所以，目前唯一的解决方案是使用

:target:

格式来编写

URL#anchor

，这样会引入需要手动维护的 URL，带来严重不便。