我正在使用 Sphinx 记录将部署在不同服务器中的 Web 服务。该文档充满了供用户单击的 URL 示例，它们应该可以正常工作。我的问题是主机、端口和部署根目录会有所不同，并且必须为每次部署重新生成文档。
我尝试定义这样的替换：
|base_url|/path
.. |base_url| replace:: http://localhost:8080
但是生成的 HTML 不是我想要的（生成的链接中不包含“/path”）：
<a href="http://localhost:8080">http://localhost:8080</a>/path
有人知道如何解决这个问题吗？
【问题讨论】：
标签： python python-sphinx substitution restructuredtext
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 的链接。如您所见，角色中给出的目标被替换为基本 URL 中的%s。
链接标题取决于元组中的第二项，前缀：
如果前缀为无，则链接标题为完整 URL。
如果前缀是空字符串，则链接标题是角色内容中给出的部分 URL（在本例中为 123。）
如果前缀是非空字符串，则链接标题是部分 URL，由前缀前缀 - 在上面的示例中，链接标题将是问题 123。
您还可以使用生成链接的其他角色支持的常用“显式标题”语法，即:issue:`this issue <123>`。在这种情况下，前缀不相关。
【讨论】：
conf.pyextensions = ['sphinx.ext.extlinks']。不得不找别人conf.py搞清楚。
%s。
我遇到了类似的问题，我还需要替换图像目标中的 URL。
extlinks 用作图像:target: 属性的值时不会扩展。
最终，我编写了一个自定义的 sphinx 转换，它重写了以给定前缀开头的 URL，在我的例子中是 http://mybase/。下面是 conf.py 的相关代码：
from sphinx.transforms import SphinxTransform
class ReplaceMyBase(SphinxTransform):
default_priority = 750
prefix = 'http://mybase/'
def apply(self):
from docutils.nodes import reference, Text
baseref = lambda o: (
isinstance(o, reference) and
o.get('refuri', '').startswith(self.prefix))
basetext = lambda o: (
isinstance(o, Text) and o.startswith(self.prefix))
base = self.config.mybase.rstrip('/') + '/'
for node in self.document.traverse(baseref):
target = node['refuri'].replace(self.prefix, base, 1)
node.replace_attr('refuri', target)
for t in node.traverse(basetext):
t1 = Text(t.replace(self.prefix, base, 1), t.rawsource)
t.parent.replace(t, t1)
return
# end of class
def setup(app):
app.add_config_value('mybase', 'https://en.wikipedia.org/wiki', 'env')
app.add_transform(ReplaceMyBase)
return
这扩展了以下第一个来源以指向英文维基百科。
当 conf.py 设置 mybase="https://es.wikipedia.org/wiki" 时，链接将指向西班牙语 wiki。
* inline link http://mybase/Helianthus
* `link with text <http://mybase/Helianthus>`_
* `link with separate definition`_
* image link |flowerimage|
.. _link with separate definition: http://mybase/Helianthus
.. |flowerimage| image:: https://upload.wikimedia.org/wikipedia/commons/f/f1/Tournesol.png
:target: http://mybase/Helianthus
【讨论】：
好的，这就是我的做法。首先，apilinks.py（Sphinx 扩展）：
from docutils import nodes, utils
def setup(app):
def api_link_role(role, rawtext, text, lineno, inliner, options={},
content=[]):
ref = app.config.apilinks_base + text
node = nodes.reference(rawtext, utils.unescape(ref), refuri=ref,
**options)
return [node], []
app.add_config_value('apilinks_base', 'http://localhost/', False)
app.add_role('apilink', api_link_role)
现在，在conf.py 中，将'apilinks' 添加到扩展列表并为'apilinks_base' 设置适当的值（否则，它将默认为'http://localhost/'）。我的文件如下所示：
extensions = ['sphinx.ext.autodoc', 'apilinks']
# lots of other stuff
apilinks_base = 'http://host:88/base/'
用法：
:apilink:`path`
输出：
<a href="http://host:88/base/path">http://host:88/base/path</a>
【讨论】：
【讨论】：