Sphinx 中匿名和非匿名超链接的区别

Question

在我的 Sphinx 文件之一中，我有这个：

.. _pyjnius:

Pyjnius
=======

When running on Android, a version of the `Pyjnius <https://pyjnius.readthedocs.io/en/stable/>`_
library is available. This allows advanced creators to call into the Android
libraries.

它似乎按照我想要的方式编译，但我收到一条警告说

WARNING: Duplicate explicit target name: "pyjnius"

。我遇到了“这个问题”，建议用两个下划线而不是一个下划线结束链接，这被称为匿名链接。这不是完全相同的问题：在该问题中有两个同名的链接，而在我的情况下只有一个链接，但我尝试了解决方案并且它有效。

`this <link>`_

和

 `that <link>`__

（又名匿名链接和非匿名链接）之间有什么区别？如果我将所有外部超链接转换为双下划线语法会发生什么？

Answer 1

匿名链接和非匿名链接之间（...）有什么区别

当您声明

超链接目标

时，会创建

引用名称。但如果目标是匿名的，则不会使用名称来匹配对其目标的引用。以下文档中的引用对其进行了总结：

匿名超链接

引用的引用名称不用于将引用与其目标相匹配。

相反，文档中匿名超链接引用和目标的顺序很重要

：第一个匿名引用将链接到第一个匿名目标。 文档中匿名超链接引用的数量必须与匿名目标的数量相匹配。

现在是嵌入在同一个句子中的问题的第二部分：

`this <link>`_

和

 `that <link>`__

有什么区别

如果你仔细阅读reStructuredText规范，没有给出简洁的

`Title <Link>`_

语法的清晰示例，但它是一个外部超链接目标（因为URL指向文档的外部）。发生的情况是

Title

充当目标的参考名称，因此会出现逐字错误：

“重复显式 

目标名称”。 使用双下划线

__

将超链接目标声明为匿名会导致

Title

不再用作目标名称，因此不再存在重复的目标名称，因为声明的顺序用于将匿名目标匹配到

link

。总结：

就我而言，只有一个链接

是的，但是错误消息所说的是有一个

“重复的显式目标名称”

问题是Pyjnius在该部分上方被声明为目标，并再次显式地作为标题（充当目标名称） ) 在链接中使用缩写语法。

另请注意，引用名称（目标或标题）已标准化，因此不区分大小写。因此，在您的示例中，名称

Pyjnius <URL>

最终被标准化为

pyjnius

，这与该部分上方的目标名称相同。

参考名称

大小写标准化（所有字母字符都转换为小写）。

Answer 2

3次

：

“显式超链接目标”语法
• .. _pyjnius:

  使下一个元素成为名为“pyjnius”的显式目标。

默认情况下，每个部分标题也是一个“
• 隐式超链接目标

  ”。

  带有嵌入目标的超链接
Pyjnius <https:…>_
• 是超链接引用和显式命名超链接目标的简写。
  默认情况下，显式超链接目标会默默地覆盖隐式超链接目标。然而，两个外部目标发生冲突：由于“处于同一级别”，Docutils/Sphinx 不知道使用什么作为目标，如果简单的超链接引用
pyjnius_

出现在文档中的其他位置。

1复制节标题的显式目标是多余的，除非您在另一个（子）节中再次使用相同的（子）节标题，并且想要消除哪个应该是同名链接的目标的歧义。）