Sphinx 代码块内的替换不会被替换

Question

在这个由 Sphinx 渲染的 reST 示例中，|yaco_url|不会被替换，因为它位于代码块中：

.. |yaco_url| replace:: http://yaco.es/

You can use wget to download it:

.. code-block:: console

    $ wget |yaco_url|package.tar.gz

我想知道是否有某种方法可以强制替换 |yaco_url|在渲染代码块之前。

Answer 1

使用“parsed-literal”指令。

.. parsed-literal::

    ./home/user/somecommand-|version|

来源：https://groups.google.com/forum/?fromgroups=#!主题/sphinx-dev/ABzaUiCfO_8：

Answer 2

找到了一个更好的解决方案（在我看来），可以在 :samp: 等其他指令中使用，并且可能对未来的读者有用。

config.py：

def ultimateReplace(app, docname, source):
    result = source[0]
    for key in app.config.ultimate_replacements:
        result = result.replace(key, app.config.ultimate_replacements[key])
    source[0] = result

ultimate_replacements = {
    "{TEST}" : "replaced"
}

def setup(app):
   app.add_config_value('ultimate_replacements', {}, True)
   app.connect('source-read', ultimateReplace)

这种标记：

.. http:get:: testing/replacement/{TEST}

正确生成如下：

testing/replacement/replaced

注意，如果使用它来替换 :samp: 指令中的参数，则双括号 { 是要求。

:samp:`func({{TEST}})`.

来源：https://github.com/sphinx-doc/sphinx/issues/4054