我正在使用Sphinx来记录一个将部署在不同服务器的Web服务。文档中充满了用户可以点击并应该正常工作的URL示例。但我的问题是主机、端口和部署根目录将会变化，每次部署都需要重新生成文档。
我尝试像这样定义替换：
|base_url|/path
.. |base_url| replace:: http://localhost:8080
但是生成的HTML并不是我想要的（在生成的链接中不包括“/path”）：
<a href="http://localhost:8080">http://localhost:8080</a>/path
有人知道如何解决这个问题吗？
Sphinx v1.0的新功能：
sphinx.ext.extlinks——用于缩短外部链接的标记
https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
该扩展添加了一个新的配置值：
extlinks
该配置值必须是一个外部站点的字典，将唯一的短别名映射到基本URL和前缀。例如，要为上述问题创建别名，您可以添加:
extlinks = {'issue':
('http://bitbucket.org/birkenfeld/sphinx/issue/%s', 'issue ')}
:issue:`123`。 这将插入一个链接到http://bitbucket.org/birkenfeld/sphinx/issue/123。 如您所见，在角色中给定的目标替换了基本URL中的%s。: issue：`this issue <123>` 。 在这种情况下，前缀无关紧要。conf.py文件中：extensions = ['sphinx.ext.extlinks']。不得不查看别人的conf.py文件才找到这个答案。 - ideasman42我遇到了类似的问题，需要替换图像目标中的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
mybase="https://es.wikipedia.org/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>