重组文本（Sphinx）：用文件名替代吗？

Question

我想从一个模板创建多个文件，这些文件的区别仅在于变量名。例如：

（（file1.rst）：

.. |variable| replace:: 1
.. include template.rst

（template.rst）：

Variable |variable|
=====================

Image
-------

.. image:: ./images/|variable|-image.png

当然，我有一个名为“ ./images/1-image.png”的图像。替换“ |变量|”由“ 1”的标题效果很好，但在图像文件名中效果不佳，在编译时，我得到：

WARNING: image file not readable: ./images/|variable|-image.png

我如何也可以通过reST在变量名中进行替换？ （如果这有任何更改，请使用Sphinx）。

Answer 1

这里有两个问题：替换问题和解析顺序问题。

对于第一个问题，替代参考 |variable|不能有相邻字符（除了空格，或者_代表超链接），否则它将不会解析为替代参考，因此您需要对其进行转义：] >

./images/\ |variable|\ -image.png
但是，第二个问题迫在眉睫。虽然我不确定细节，但似乎reST无法解析其他指令中的替换。我认为它首先解析image指令，该指令将其放入文档树中，因此超出了替换机制的范围。同样，我认为无法使用替换插入要解析的内容（例如.. |img1| replace::`.. image:: images/1-image.png`）。这些都是基于一些测试和我对official documentation的不完全理解而进行的推测，因此，知识渊博的人可以纠正我在这里所说的内容。

我认为您知道实际的图像替换指令（而不是文本替换），但我认为它不能达到您想要的通用性（您仍然需要单独的图像指令，因为来自| variable |），但无论如何看起来都是这样：

.. |img1| image:: images/1-image.png
由于使用的是Sphinx，因此您可以尝试创建自己的指令扩展名（有关信息，请参见this answer，但它不能解决内部替换标记问题。

Answer 2

在这种情况下，您必须创建一个自定义指令，因为Sphinx不允许您替换图像路径。您可以按以下方式更改Sphinx Figure指令，并使用它代替image指令。