reST / Sphinx中的链接内部替换

Question

我正在使用Sphinx来记录将在不同服务器中部署的Web服务。该文档包含许多URL示例，供用户单击，它们应该可以正常工作。我的问题是主机，端口和部署根目录会有所不同，并且必须为每个部署重新生成文档。

我试图定义这样的替换：

|base_url|/path
.. |base_url| replace:: http://localhost:8080

但是生成的HTML不是我想要的（生成的链接中不包含“ / path”）：

<a href="http://localhost:8080">http://localhost:8080</a>/path

有人知道该如何解决吗？

Answer 1

Sphinx v1.0的新功能：

sphinx.ext.extlinks –标记以缩短外部链接

https://www.sphinx-
doc.org/en/master/usage/extensions/extlinks.html

该扩展添加了一个新的配置值：

外部链接

此配置值必须是外部站点的字典，并将唯一的简短别名映射到基本URL和前缀。例如，要为上述问题创建别名，您可以添加

extlinks = {'issue': 
    ('http://bitbucket.org/birkenfeld/sphinx/issue/%s', 'issue ')}

现在，您可以将别名用作新角色，例如:issue:123`。然后，这会插入一个指向[http://bitbucket.org/birkenfeld/sphinx/issue/123](http://bitbucket.org/birkenfeld/sphinx/issue/123)的链接。如您所见，在角色中给定的目标已替换为基本URL中的%s`。

链接标题取决于元组中的第二项，即前缀：

如果前缀为None，则链接标题为完整URL。如果前缀为空字符串，则链接标题为角色内容中给出的部分URL（在这种情况下为123）。如果前缀为非空字符串，则链接标题为部分URL，前缀为前缀–在上面的示例中，链接标题将是问题123。您还可以使用生成链接的其他角色（即）所支持的通常的“显式标题”语法:issue:this
issue <123>``。在这种情况下，前缀不相关。