是否可以在重组文本（或狮身人面像）中重用另一个文件中定义的超链接

Question

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

.. _foo: http://whosebug.com

`foo`_ is a website

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

Followup

我按照 Steve Piercy 的建议使用了 extlinks 扩展。其实现和docstring可见here on github.

就我而言，我在 conf.py

中定义维基百科 link

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

并在 .rst 文件中，像

一样使用它们

:wiki:`Einstein <Albert_Einstein>`

其中 Einstein 将显示为 link 到 https://en.wikipedia.org/wiki/Albert_Einstein

Answer 1

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

#重复你自己

把你完整的休息放在每个文件里。你可能不想要那个。

#combined rst_epilog 和替换

这个很聪明。配置 rst_epilog value, in your conf.py along with a substition with the replace directive:

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

然后休息：

|foo|_ is a website

产量：

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

#extlinks

对于外部网站的链接，您希望有一个基础 URL 并附加路径段或参数，您可以在 conf.py:

中使用 extlinks

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

然后在休息时：

:so:`questions/49016433`

产量：

<a class="reference external"
 href="
 
</a>

#intersphinx

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

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

然后在休息时：

: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

这是另一种解决方案：它有点老套，并且与官方支持的共享外部链接的方式有点不同。

首先完成设置然后：

在 conf.py 中添加 commonlinks 条目 extensions
在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`

设置

只需要将文件 commonlinks.py:

复制到 sphinx/ext 目录

# -*- 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

Answer 3

这可能来得有点晚，但我找到了一个非常适合我的解决方案，它不在已经给出的答案中。

在我的例子中，我创建了一个包含项目中使用的所有 link 的文件，将其另存为 /include/links.rst，看起来像：

.. _PEP8: https://www.python.org/dev/peps/pep-0008/
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
.. _googledoc: https://google.github.io/styleguide/pyguide.html

然后是文件 a.rst 和 b.rst，如下所示：

.. include:: /include/links.rst

File A.rst
##########

Click `here <PEP8_>`_ to see the PEP8 coding style

Alternatively, visit either:
    - `Numpy Style <numpydoc_>`_
    - `Google Style <googledoc_>`_

和


.. include:: /include/links.rst

File B.rst
##########

You can visit `Python's PEP8 Style Guide <PEP8_>`_

For docstrings, you can use either `Numpy's <numpydoc_>`_ or `Google's <googledoc_>`_

分别

两种情况下产生的输出是：

和

分别

此外，我想强调一个事实，我实际上确实在努力实现这一目标，即在不同位置为相同的 link 使用不同的名称（显示的文本），并且我已经实现了双 _，一个在 <..._> 里面，一个在外面。

是否可以在重组文本（或狮身人面像）中重用另一个文件中定义的超链接

Is it possible to reuse hyperlink defined in another file in restructuredtext (or sphinx)

restructuredtext

python-sphinx

设置