include - rst 文件中的“.. 替换”是什么意思？

Question

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

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

我试图找出这句话的.. substitutions意思，但我什么也没找到。

如果我删除该行.. substitutionssphinx 命令会发出警告

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

并且页面未呈现。

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

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

标签： includecommentspython-sphinxrestructuredtext

Answer 1

在这两行

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

第一行只是一个注释。

注释

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

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

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

话虽如此，您.. include::在 reST 中的某处使用了一个指令，该指令显然使用了该end-before选项。通过删除.. substitutions评论，您可能会删除end-before选项中使用的文本。看到这个出色的答案。

指令类型：“include” - reStructuredText 指令。

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