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

Question

Suppose I have two files a.rst and b.rst in the same folder, and a.rst looks like this

.. _foo: http://stackoverflow.com

`foo`_ is a website

It seems using foo in b.rst is not allowed. Is there a way to define hyperlinks and use them in multiple files?

Followup

I used the extlinks extension as Steve Piercy suggested. Its implementation and docstring can be seen here on github.

In my case, I define wikipedia link in my conf.py

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

and in the .rst files, use them like

:wiki:`Einstein <Albert_Einstein>`

where Einstein will be displayed as a link to https://en.wikipedia.org/wiki/Albert_Einstein

Answer 1

There are at least four possible solutions.

1. repeat yourself

Put your complete reST in each file. You probably don't want that.

2. combined rst_epilog and substitution

This one is clever. Configure the rst_epilog value, in your conf.py along with a substition with the replace directive:

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

and reST:

|foo|_ is a website

yields:

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

3. extlinks

For links to external websites where you want to have a base URL and append path segments or arguments, you can use extlinks in your conf.py:

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

Then in your reST:

:so:`questions/49016433`

Yields:

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

4. intersphinx

For external websites that are documentation generated by Sphinx, then you can use intersphinx, in your conf.py:

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

Then in your reST:

:py:mod:`doctest`

Yields:

<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

This might come a bit late but I have found a solution that works very neatly for me and it is not among the answers already given.

In my case, I create a file with all the links used in my project, save it as /include/links.rst, and looking something like:

.. _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

Then there are the files a.rst and b.rst looking like:

.. 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_>`_

and

.. 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_>`_

respectively.

The produced output for both cases is:

and

respectively.

Moreover, I would like to emphasize the fact of which I was actually really struggling to achieve, to use different names (displayed text) for the same link at different locations and which I have achieved with the double _, one inside the <..._> and another outside.