Sphinx中如何在无空格的等宽文本块中正确引用|version|变量

嘿，我之前也碰到过一模一样的问题！Sphinx默认会把反引号包裹的等宽文本（也就是代码块/行）当作字面量处理，所以里面的|version|不会被自动替换。这里有几个实用的解决办法，你可以根据自己的场景选：

• 方法一：使用:code:角色
  这是最直接的方式，用Sphinx内置的:code:角色来包裹需要等宽显示且带变量的内容，它会先解析里面的替换变量，再渲染成等宽格式。比如：
  :code:pip install -U foo_project==|version|
  你的Git链接也可以这么写：
  :code:git+https://github.com/foo_username/foo_project.git@|version|
  这样既保留了等宽的代码样式，|version|也能被正确替换成当前版本号。

• 方法二：用Jinja2模板语法写代码块
  如果你习惯用多行代码块（比如带语法高亮的那种），可以借助Sphinx的Jinja2模板支持（默认已经启用，不用额外装扩展），把代码里的|version|换成{{ version }}就行。比如：

  pip install -U foo_project=={{ version }}
  

  对应的Git链接代码块：

  git+https://github.com/foo_username/foo_project.git@{{ version }}
  

  这样整个代码块里的版本号都会被正确替换，格式也保持等宽。

• 方法三：预定义带格式的替换变量
  如果这段带版本号的代码需要在文档里多次使用，你可以先在rst文件里预定义好替换项：

  .. |pip_install_cmd| replace:: ``pip install -U foo_project==|version|``
  .. |git_repo_link| replace:: ``git+https://github.com/foo_username/foo_project.git@|version|``
  

  之后在文档里直接用|pip_install_cmd|或者|git_repo_link|，就能一键渲染出带正确版本号的等宽文本了，非常适合重复使用的场景。

这些方法都不需要给|version|加空格，就能让Sphinx正确识别并替换变量，亲测有效哦！

备注：内容来源于stack exchange，提问作者Mike Pennington