CODEWITHSUNDEEP
python-sphinxrestructuredtext
LukeDev
LukeDev

Reputation: 541

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?

Upvotes: 4

Views: 2199

Answers (1)

Steve Piercy
Steve Piercy

Reputation: 15105

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.

Upvotes: 5

Related Questions