Standardizing a link using a global variable in Sphinx documentation

问题

I'm using Sphinx to document a project for work. I want to use the same link that points to a download on multiple pages throughout my documentation.

For example: home.rst:

Hi
==

I want you to download_ my project.

.. _download: blah.com/download

other_page.rst

Hello Again
===========
You can also download_ it here.

.. _download: blah.com/download

Is there some way to have one variable that each page points to so when the link needs updated only on variable needs to be updated?

回答1:

The best option is to use a substitution, rst_epilog, and raw-html as described in this answer for mailto links.

In your conf.py:

rst_epilog = """
.. role:: raw-html(raw)
   :format: html

.. |download| replace:: :raw-html:`<a href="https://blah.com/download/">download</a>`
"""

In your *.rst:

Please |download| my file.

The extlink extension is close, but assumes that you will want to use an URL as the base for other links to the site.

来源：https://stackoverflow.com/questions/57417808/standardizing-a-link-using-a-global-variable-in-sphinx-documentation