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 - 缩短外部链接的标记

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

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

<强> extlinks

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

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

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

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

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

Answer 2

好的，我就是这样做的。首先，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>

Answer 3

你可以写一个Sphinx extension创建role之类的

:apilink:`path`

并从中生成链接。我从来没有这样做过，所以我不能不给这个指针，对不起。您应该尝试查看各种角色的实现方式。我想，很多都与你的需求非常相似。

Answer 4

我遇到了类似的问题，需要在图像目标中也替换URL。 extlinks用作图像:target:属性的值时不会扩展。最终，我编写了一个自定义sphinx转换，该转换重写了以给定前缀（在我的情况下为http://mybase/）开始的URL。这是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

reST / Sphinx中链接内的替换

4 个答案: