Sphinx中匿名与非匿名超链接的差异及语法疑问

问题背景 #

在Sphinx文档中定义了锚点.. _pyjnius:后，使用单下划线外部链接语法Pyjnius <外部URL>_时，触发了「Duplicate explicit target name: "pyjnius"」的警告；改用双下划线的匿名链接语法Pyjnius <外部URL>__后，警告消失。

两种链接语法的核心差异 #

• 单下划线链接（text <url>_）：属于命名链接，Sphinx会将链接文本（比如这里的Pyjnius）当作一个可重复引用的目标名称。如果文档内已经存在同名的显式锚点（如.. _pyjnius:），就会触发重复目标警告——因为Sphinx会误认为你要定义一个和现有锚点同名的链接目标。
• 双下划线链接（text <url>__）：属于匿名链接，不会创建可被引用的目标名称，仅生成一个指向外部URL的超链接。它不会和文档内的任何锚点名称冲突，也无法被文档其他位置引用。

全转双下划线语法的影响 #

优势 #

• 彻底规避「重复目标名称」类警告，尤其适合外部链接文本与文档内锚点名称重合的场景。
• 无需考虑命名冲突，语法更轻量化，适合仅需单次跳转的外部链接场景。

潜在局限 #

• 无法复用链接：如果文档中多次需要跳转至同一外部URL，单下划线语法只需定义一次，后续用text_即可引用；双下划线语法每次都要完整书写URL，维护成本更高。
• 丢失语义提示：单下划线的命名链接能通过目标名称让其他编写者快速理解链接指向；双下划线匿名链接没有这类语义标识，可读性稍弱。

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