变量替换在 Sphinx 中无法正常工作 [英] Variable substitution not working properly in Sphinx

问题描述

我有一个使用

显然替换在格式化的源代码块中不起作用，这非常不方便.

是否可以解决此问题?

PS:我也用 rst_prolog 尝试过，结果相同.

解决方案

这将使替换工作:

.. 解析字面量::git 克隆 https://github.com/my-organization/my-repo.gitcd my-repogit checkout |MY_VERSION|

使用 parsed-literal 指令，您可以有替换(和其他内联标记)，但没有语法突出显示.

使用 代码块(或sourcecode，或highlight)，你可以有语法高亮但不处理内联标记.

I have a documentation project made with Sphinx. I am using global variables by means of the configuration key rst_epilog. My conf.py file contains the following:

rst_epilog = """
.. |MY_VERSION| replace:: 2.1.0
"""

Then, in a rst page, I'm using the formerly defined variable (VERSION) as follows:

The version of my repo is: |MY_VERSION|

.. sourcecode:: bash

    git clone https://github.com/my-organization/my-repo.git
    cd my-repo
    git checkout |MY_VERSION|

After building the documentation, in the resulting HTML, the first variable is correctly substituted, but not the second:

Clearly the substitution does not work inside formatted source code blocks, which is very inconvenient.

Is it possible to workaround this issue?

PS: I also tried with rst_prolog with the same result.

解决方案

This will make the substitution work:

.. parsed-literal::

   git clone https://github.com/my-organization/my-repo.git
   cd my-repo
   git checkout |MY_VERSION|

With the parsed-literal directive, you can have substitutions (and other inline markup) but there is no syntax highlighting.

With code-block (orsourcecode, or highlight), you can have syntax highlighting but inline markup is not processed.

这篇关于变量替换在 Sphinx 中无法正常工作的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！