用 reStructuredText (Sphinx) 替换文件名? [英] Substitution in a file name with reStructuredText (Sphinx)?
问题描述
我想从一个模板创建多个文件,这些文件仅在变量名称上有所不同.例如:
I want to create several files from a single template, which differ only by a variable name. For example :
(file1.rst):
(file1.rst):
.. |variable| replace:: 1
.. include template.rst
(模板.rst):
Variable |variable|
=====================
Image
-------
.. image:: ./images/|variable|-image.png
当然,我有一个名为./images/1-image.png"的图像.|变量|"的替换通过1"在标题中效果很好,但在图像文件名中无效,并且在编译时我得到:
where of course I have an image called "./images/1-image.png". The substitution of "|variable|" by "1" works well in the title, but not in the image file name, and at compilation I get :
WARNING: image file not readable: ./images/|variable|-image.png
我怎样才能让 reST 也在变量名中进行替换?(如果这有任何改变,我正在使用 Sphinx).
How can I get reST to make the substitution in the variable name too? (if this changes anything, am using Sphinx).
推荐答案
这里有两个问题:替换问题和解析顺序问题.
There are two problems here: a substitution problem, and a parsing order problem.
对于第一个问题,替换引用 |variable|
不能有相邻的字符(除了空格或 _ 用于超链接)否则它不会解析为替换引用,因此您需要对其进行转义:
For the first problem, the substitution reference |variable|
cannot have adjacent characters (besides whitespace or maybe _ for hyperlinking) or else it won't parse as a substitution reference, so you need to escape it:
./images/\ |variable|\ -image.png
然而,第二个问题即将来临.虽然我不确定细节,但似乎 reST 无法解析其他指令中的替换.我认为它首先解析图像指令,将其放入文档树中,因此超出了替换机制的范围.同样,我认为不可能使用替换来插入要解析的内容(例如 ..|img1|replace::`..image::images/1-image.png`
).这都是基于一些测试和我对 官方文档,所以更有见识的人可以纠正我在这里所说的.
However, the second problem is waiting around the corner. While I'm not certain of the details, it seems reST is unable to parse substitutions inside other directives. I think it first parses the image directive, which puts it in the document tree and thus out of reach of the substitution mechanism. Similarly, I don't think it's possible to use a substitution to insert content intended to be parsed (e.g. .. |img1| replace::`.. image:: images/1-image.png`
). This is all speculative based on some tests and my incomplete comprehension of the official documentation, so someone more knowledgeable can correct what I've said here.
我认为您了解实际的图像替换指令(与文本替换相反),但我认为它没有达到您的目标(您仍然需要一个单独的图像指令来自 |variable|),但无论如何它看起来像这样:
I think you're aware of the actual image substitution directive (as opposed to text substitution), but I don't think it attains the generality you're aiming for (you'll still need a separate directive for the image as from the |variable|), but in any case it looks like this:
.. |img1| image:: images/1-image.png
由于您使用的是 Sphinx,您可以尝试创建自己的指令扩展(参见 这个答案 信息),但它不会解决内部标记替换问题.
Since you're using Sphinx, you can try creating your own directive extension (see this answer for information), but it won't solve the substitutions-inside-markup problem.
这篇关于用 reStructuredText (Sphinx) 替换文件名?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!