Sphinx中嵌入外部URL解析异常，该如何解决？

问题描述 #

使用Sphinx为Python常量添加文档注释时，编写了如下代码：

#: `RFC 8415 §7.6 <https://www.rfc-editor.org/rfc/rfc8415.html#section-7.6>`_
_SOL_TIMEOUT = 1

Sphinx解析后出现异常，生成的文档效果如下：

pkg.module._SOL_TIMEOUT=1
/www.rfc-editor.org/rfc/rfc8415.html#section-7.6>_ **Type::** RFC 8415 §7.6

（补充：曾尝试将非ASCII字符'§'替换为'S'，问题未得到改善）

询问：是否有办法让嵌入的外部URL正常工作，还是只能使用命名URL语法？

可行解决方案 #

1. 调整链接格式，避免反引号包裹完整URL #

去掉反引号对URL的包裹，直接使用Sphinx兼容的链接写法；若需要强调文本，单独用星号包裹链接文本即可：

#: *RFC 8415 §7.6* <https://www.rfc-editor.org/rfc/rfc8415.html#section-7.6>
_SOL_TIMEOUT = 1

如果不需要强调，直接写链接：

#: RFC 8415 §7.6 <https://www.rfc-editor.org/rfc/rfc8415.html#section-7.6>
_SOL_TIMEOUT = 1

2. 使用命名URL语法（推荐） #

先在文档的合适位置（比如项目conf.py或单独的rst文档）定义命名锚点：

.. _RFC 8415 §7.6: https://www.rfc-editor.org/rfc/rfc8415.html#section-7.6

然后在常量注释中引用该锚点：

#: `RFC 8415 §7.6`_
_SOL_TIMEOUT = 1

这种写法能彻底避免Sphinx的解析歧义，是最稳妥的方案。

问题原因 #

Sphinx自动解析常量注释时，会将: 后的内容识别为类型说明字段。当用反引号包裹带尖括号的完整URL时，解析器会错误拆分尖括号内的内容，把<https误判为类型标识，导致URL被截断、格式混乱。

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