是否可以使用 sphinx 使用 :class: 角色链接到特定 URL？

Question

我正在使用 Sphinx 来记录一个 python 包，该包包装了一个专有 API，据我所知，该 API 并未使用 Sphinx 进行记录。 API 文档提供了有用的信息，但 URL 的格式不是 sphinx 可以自动生成链接的格式。是否可以将字符串在语义上标记为类，同时手动指定链接目标？

我尝试过：

:class:`Class <https://api.documentation/some/path/to_class_constructor.htm>`_

但这会引发

WARNING: Mismatch: both interpreted text role prefix and reference suffix.

。然后我也尝试了

:class:`Class <https://api.documentation/some/path/to_class_constructor.htm>`

不会发出警告，但也不会生成超链接。

根据 Steve Piercy 下面的评论，

sphinx.ext.extlinks

扩展使文档更加清晰，但它失去了我更愿意保留的语义含义。

是否可以以某种方式显示引用类的文本，同时链接到外部 API 文档？

Answer 1

这是可能的，但很麻烦，因为 rST 中缺少对嵌套内联标记的支持。

常见的解决方法是定义替换并将其与超链接语法一起使用，例如

.. |class-1| replace:: :sub:`Class`

This is |class-1|__

__ https://api.documentation/some/path/to_class_constructor.htm