“.. 替换”在 rst 文件中是什么意思？

如何解决“.. 替换”在 rst 文件中是什么意思？

我有一个用 Sphinx 渲染的 README.rst 文件。在该 .rst 文件的末尾，我看到以下两行：

.. substitutions
.. |banner| image:: docs/source/logo/Banner.png

我试图找出短语 .. substitutions 的意思，但我什么也没找到。

如果我删除行 .. substitutions，sphinx 命令会发出警告

Problem with "end-before" option of "include" directive:
Text not found.

并且页面未呈现。

任何想法在哪里可以找到有关该指令的适当文档，以及此错误消息的含义？

谷歌搜索没有帮助。对于错误消息，我只发现了 3(!) 个提示。

解决方法

这两行

.. substitutions
.. |banner| image:: docs/source/logo/Banner.png

第一行只是一个注释。

Comments

可以在显式标记开始之后的行上使用任意缩进文本。为确保不会识别任何其他显式标记结构，请将“..”单独放在一行上：

但第二行不是注释，它必须在缩进块内。

+-------+----------------------+
| ".. " | comment              |
+-------+ block                |
        |                      |
        +----------------------+

话虽如此，您在您的休息中的某处使用了 .. include:: 指令，该指令显然使用了 end-before 选项。通过删除 .. substitutions 注释，您可能会删除 end-before 选项中使用的文本。见this excellent answer。

Directive Type: "include" - reStructuredText 指令。

end-before ：要在外部数据文件中查找的文本 仅包含指定文本第一次出现之前（但在任何之后的文本之后）的内容。