reStructured Text(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`).这是基于一些测试和我对官方文档的不完全理解的所有推测,所以更有知识的人可以纠正我在这里所说的.

我认为你知道实际的图像替换指令(而不是文本替换),但我不认为它达到了你的目标通用性(你仍然需要一个单独的图像指令,因为|变量|),但无论如何它看起来像这样:

.. |img1| image:: images/1-image.png

由于您正在使用Sphinx,您可以尝试创建自己的指令扩展(请参阅此答案以获取信息),但它不能解决替换内部标记问题.