reST /狮身人面像链接内的替换 [英] Substitutions inside links in reST / Sphinx

问题描述

我正在使用Sphinx来记录将部署在不同服务器中的Web服务。文档中填写了用户点击的URL示例，它们应该正常工作。我的问题是，主机，端口和部署根将会有所不同，并且必须为每次部署重新生成文档。

I am using Sphinx to document a webservice that will be deployed in different servers. The documentation is full of URL examples for the user to click and they should just work. My problem is that the host, port and deployment root will vary and the documentation will have to be re-generated for every deployment.

我尝试定义如下替换： / p>

I tried defining substitutions like this:

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

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

But the generated HTML is not what I want (doesn't include "/path" in the generated link):

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

有人知道如何解决方案

推荐答案

Sphinx v1.0中的新功能：

New in Sphinx v1.0:

sphinx.ext.extlinks - 缩短外部链接的标记

sphinx.ext.extlinks – Markup to shorten external links

http://sphinx.pocoo.org/ext/extlinks.html

扩展程序会添加一个新的配置值：

The extension adds one new config value:

extlinks

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

This config value must be a dictionary of external sites, mapping unique short alias names to a base URL and a prefix. For example, to create an alias for the above mentioned issues, you would add

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

现在，您可以使用别名作为新角色，例如：问题：`123` 。然后插入一个链接到 http://bitbucket.org/birkenfeld/sphinx/issue/123。正如你所看到的，角色中给出的目标在基本URL中替换为％s 。

Now, you can use the alias name as a new role, e.g. :issue:`123`. This then inserts a link to http://bitbucket.org/birkenfeld/sphinx/issue/123. As you can see, the target given in the role is substituted in the base URL in the place of %s.

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

The link caption depends on the second item in the tuple, the prefix:

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

If the prefix is None, the link caption is the full URL. If the prefix is the empty string, the link caption is the partial URL given in the role content (123 in this case.) If the prefix is a non-empty string, the link caption is the partial URL, prepended by the prefix – in the above example, the link caption would be issue 123. You can also use the usual "explicit title" syntax supported by other roles that generate links, i.e. :issue:`this issue <123>`. In this case, the prefix is not relevant.

这篇关于reST /狮身人面像链接内的替换的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！