python-sphinx - 在 Sphinx 文档中使用全局变量标准化链接

Question

我正在使用 Sphinx 来记录工作项目。我想在整个文档中使用指向多个页面上的下载的相同链接。

例如: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

有没有办法让每个页面都指向一个变量，这样当链接需要更新时，只需要更新变量？

Answer 1

最好的选择是使用 substitution , rst_epilog和 raw-html 如本 answer for mailto links 所述.

在你的conf.py中:

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

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

在你的*.rst中:

Please |download| my file.

extlink extension很接近，但假定您希望使用 URL 作为指向该站点的其他链接的基础。