使用 Sphinx 文档中的全局变量标准化链接 [英] Standardizing a link using a global variable in Sphinx documentation

问题描述

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

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.

例如:主页.rst:

Hi
==

I want you to download_ my project.

.. _download: blah.com/download

other_page.rst

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?

推荐答案

最好的选择是使用 substitution, rst_epilog 和 raw-html 如本 mailto 链接的答案.

The best option is to use a substitution, rst_epilog, and raw-html as described in this 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 扩展 很接近，但假设您希望使用 URL 作为指向该站点的其他链接的基础.

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

这篇关于使用 Sphinx 文档中的全局变量标准化链接的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！