Standardizing a link using a global variable in Sphinx documentation

Question

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?

Take a look at https://stackoverflow.com/q/18398548/407651 – mzjn Aug 09 '19 at 08:04 — mzjn, Aug 09 '19 at 08:04

score 5 · Answer 1 · answered Aug 08 '19 at 21:16

5

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.

answered Aug 08 '19 at 21:16

Steve Piercy

You can also just put `.. _download: blah.com/download` in `rst_epilog`. – luator May 21 '21 at 12:11

1 Answers1