使用Sphinx时，如何让rst_prolog定义的替换在反引号内容中生效？

问题（翻译后） #

我在conf.py中定义了如下替换规则：

rst_prolog = """
.. |tools| replace:: Something
"""

以下是我的rst文件内容，第1行的|tools|替换生效，但第4、5、7等行中被反引号（`）包裹的|tools|以及链接URL里的|tools|无法完成替换，请问如何让这些位置的替换生效？

1   |tools| is a community project, guided by the `CHIPS Alliance`_ under the
2   `Linux Foundation`_.

3   We appreciate and welcome your contributions in whatever form; please see
4   `Contributing to |tools|
5   <https://github.com/|tools|/|tools|/blob/master/docs/CONTRIBUTING.rst>`_.
6   Thanks to our `Contributors and Sponsors
7   <https://|tools|.org/guide/latest/contributors.html>`_.

8   |tools| also supports and encourages commercial support models and
9   organizations; please see `|tools| Commercial Support
10   <https://|tools|.org/|tools|_commercial_support>`_.

问题原因 #

Sphinx默认不会处理反引号包裹的内联代码和链接URL部分中的替换标记（如|tools|），这两类内容会被当作字面量解析，跳过替换逻辑。

解决方法 #

1. 处理链接中的替换（文本+URL）

放弃内联链接写法，改用「链接文本+单独定义链接目标」的方式，同时在conf.py中用Python变量动态生成替换规则和链接，确保URL内容也能被替换：

修改conf.py：

# 统一管理替换变量，后续只需修改此处
TOOLS_NAME = "Something"

rst_prolog = f"""
.. |tools| replace:: {TOOLS_NAME}
# 预定义所有链接目标，用Python变量生成完整URL
.. _Contributing to |tools|: https://github.com/{TOOLS_NAME}/{TOOLS_NAME}/blob/master/docs/CONTRIBUTING.rst
.. _Contributors and Sponsors: https://{TOOLS_NAME}.org/guide/latest/contributors.html
.. _|tools| Commercial Support: https://{TOOLS_NAME}.org/{TOOLS_NAME}_commercial_support
"""

修改RST文件：

1   |tools| is a community project, guided by the `CHIPS Alliance`_ under the
2   `Linux Foundation`_.

3   We appreciate and welcome your contributions in whatever form; please see
4   `Contributing to |tools|`_.
6   Thanks to our `Contributors and Sponsors`_.

8   |tools| also supports and encourages commercial support models and
9   organizations; please see `|tools| Commercial Support`_.

这样链接文本里的|tools|会正常替换，URL部分则通过Python变量直接生成，无需依赖RST替换逻辑。

2. 处理反引号包裹的内联代码中的替换

有两种实用方式：

• 方式一：用Jinja2模板（推荐）
  Sphinx默认支持Jinja2模板，在conf.py中添加模板变量：

  html_context = {
      'tools_name': TOOLS_NAME
  }
  

  然后在RST中直接写：

  ``{{ tools_name }}``
  

  渲染后会自动替换为Something。

• 方式二：预定义带反引号的替换
  在conf.py的rst_prolog中添加：

  rst_prolog = f"""
  .. |tools| replace:: {TOOLS_NAME}
  .. |tools_code| replace:: `{TOOLS_NAME}`
  # 其他链接定义...
  """
  

  之后在RST里用|tools_code|代替|tools|，就能直接显示带反引号的替换后内容。

内容的提问来源于stack exchange，提问作者user3522188