重复一遍

Question

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

.. _foo: http://stackoverflow.com

`foo`_ is a website

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

跟进

史蒂夫·皮尔西建议我使用extlinks扩展名。它的实现和文档字符串可以看作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

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

重复一遍

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

组合rst_epilog和替换

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

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

和reST：

|foo|_ is a website

的产率：

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

extlinks

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

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生成的文档的外部网站，您可以在conf.py中使用intersphinx：

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

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

就我而言，我创建了一个包含项目中使用的所有链接的文件，将其另存为 /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_>`_

分别。

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

和

分别。

此外，我想强调一个事实，我实际上真的很难实现，在不同的位置为同一个链接使用不同的名称（显示的文本），而我已经通过双 _ ，一个在 <..._> 里面，另一个在外面。

Answer 3

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

首先完成设置，然后：

在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`

设置

只需将文件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

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

3 个答案:

重复一遍

组合rst_epilog和替换

extlinks

intersphinx

设置