是否可以重新使用restructuredtext（或sphinx）中另一个文件中定义的超链接

Question

假设我在同一文件夹中有两个文件a.rst和b.rst，a.rst看起来像这样

.. _foo: http://stackoverflow.com

`foo`_ is a website

似乎在foo中使用b.rst是不允许的。有没有办法定义超链接并在多个文件中使用它们？

跟进

史蒂夫·皮尔西建议我使用extlinks扩展。它的实现和docstring可以看到here on github。

就我而言，我在conf.py中定义了维基百科链接

extlinks = {'wiki': ('https://en.wikipedia.org/wiki/%s', '')}

在.rst文件中，使用它们

:wiki:`Einstein <Albert_Einstein>`

爱因斯坦将作为https://en.wikipedia.org/wiki/Albert_Einstein的链接显示

Answer 1

至少有四种可能的解决方案。

repeat yourself

将完整的reST放在每个文件中。你可能不希望这样。

combined rst_epilog and substitution

这个很聪明。在rst_epilog中配置conf.py值以及substition with the replace directive：

rst_epilog = """
.. |foo| replace:: foo
.. _foo: http://stackoverflow.com
"""

和休息：

|foo|_ is a website

收益率：

<a class="reference external" href="http://stackoverflow.com">foo</a>

extlinks

对于您希望拥有基本URL并附加路径段或参数的外部网站的链接，您可以在extlinks中使用conf.py：

extensions = [
...
    'sphinx.ext.extlinks',
...
]
...
extlinks = {'so': ('https://stackoverflow.com/%s', None)}

然后在你的reST：

:so:`questions/49016433`

产量：

<a class="reference external"
 href="https://stackoverflow.com/questions/49016433">
 https://stackoverflow.com/questions/49016433
</a>

intersphinx

对于由Sphinx生成的文档的外部网站，您可以在intersphinx中使用conf.py：

extensions = [
...
    'sphinx.ext.intersphinx',
...
]
...
intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
}

然后在你的reST：

:py:mod:`doctest`

产量：

<a class="reference external"
 href="https://docs.python.org/3/library/doctest.html#module-doctest"
 title="(in Python v3.6)">
    <code class="xref py py-mod docutils literal">
        <span class="pre">doctest</span>
    </code>
</a>

Answer 2

这是另一种解决方案：对于官方支持的共享外部链接的方式来说，它有点hacky并且有点不同。

首先完成安装然后：

1. 在conf.py中添加commonlinks条目在extensions
2. 在conf.py中配置常用链接的地图：

例如：

extensions = [
    ...,
    'sphinx.ext.commonlinks'
]

commonlinks = {
                'issues': 'https://github.com/sphinx-doc/sphinx/issues',
                'github': 'https://github.com'
              }

然后在.rst文件中你可以这样做：

The :github:`_url_` url is aliased to :github:`GitHub` and also to :github:`this`

建立

所需要的只是将文件sphinx/ext复制到commonlinks.py目录中：

# -*- coding: utf-8 -*-
"""
    sphinx.ext.commonlinks
    ~~~~~~~~~~~~~~~~~~~~~~

    Extension to save typing and prevent hard-coding of common URLs in the reST
    files.

    This adds a new config value called ``commonlinks`` that is created like this::

       commonlinks = {'exmpl': 'http://example.com/mypage.html', ...}

    Now you can use e.g. :exmpl:`foo` in your documents.  This will create a
    link to ``http://example.com/mypage.html``.  The link caption depends on the
    role content:

    - If it is ``_url_``, the caption will be the full URL.
    - If it is a string, the caption will be the role content.

"""

from six import iteritems
from docutils import nodes, utils

import sphinx
from sphinx.util.nodes import split_explicit_title


def make_link_role(base_url):
    def role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
        text = utils.unescape(text)
        if text == '_url_':
            title = base_url
        else:
            title = text
        pnode = nodes.reference(title, title, internal=False, refuri=base_url)
        return [pnode], []
    return role


def setup_link_roles(app):
    for name, base_url in iteritems(app.config.commonlinks):
        app.add_role(name, make_link_role(base_url))


def setup(app):
    app.add_config_value('commonlinks', {}, 'env')
    app.connect('builder-inited', setup_link_roles)
    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

要找到sphinx安装目录，一种方法是：

$ python 3
> import sphinx
> sphinx
<module 'sphinx' from '/usr/local/lib/python3.5/dist-packages/sphinx/__init__.py'>

然后：

% cp commonlinks.py /usr/local/lib/python3.5/dist-packages/sphinx/ext