在 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 作为其他站点链接的基础。