rest/sphinx中链接内的替换

Sphinx v1.0中的新功能:

sphinx.ext.ext links“标记以缩短外部链接”

http://sphinx.pocoo.org/ext/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>` . 在这种情况下,前缀是不相关的。

好吧,我就是这么做的。第一, apilinks.py (狮身人面像延伸部分):

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>

你可以写一个狮身人面像 extension 创建一个 role 喜欢

:apilink:`path` 

并由此生成链接。我从来没有这样做过,所以我忍不住只给了这个指针,对不起。您应该尝试看看各种角色是如何实现的。我想,很多和你需要的非常相似。

我有一个类似的问题,我需要在图像目标中替换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" 链接将指向西班牙语维基。

* 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