如何在Sphinx的versionadded admonition标题中使用变量

我在conf.py里定义了存储版本号的变量，在Sphinx文档其他地方用|version|引用都正常，但在versionadded admonition里没法生效，只能手动输版本号。示例代码如下：

.. versionadded:: |version|
   Some text here

请问有没有办法让这个变量在这里生效？

解决方法 #

这是因为Sphinx的versionadded这类指令的参数部分默认不会执行变量替换，可通过以下两种方法解决：

方法1：局部定义替换指令 #

在需要使用的.rst文件开头添加替换定义，把|version|转成可被指令参数识别的替换变量：

.. |current_version| replace:: |version|

之后直接在versionadded里用新的替换变量：

.. versionadded:: |current_version|
   Some text here

方法2：全局配置rst_prolog #

如果想在所有文档里都能用，直接在conf.py中添加全局的rst前置内容，提前定义好替换变量：

rst_prolog = f"""
.. |current_version| replace:: {version}
"""

之后在任意.rst文件里直接使用：

.. versionadded:: |current_version|
   Some text here

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