“.. substitutions”在第一个文件中是什么意思？

Question

我有一个用 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.

页面未呈现。

知道在哪里可以找到有关该指令的正确文档，以及此错误消息的含义吗？

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

Answer 1

这两行

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

第一行只是注释。

Comments

Arbitrary indented text may be used on the lines following the explicit markup start. To ensure that none of the other explicit markup constructs is recognized, leave the ".." on a line by itself:

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

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

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

Directive Type: "include" - reStructuredText Directives.

end-before : text to find in the external data file Only the content before the first occurrence of the specified text (but after any after text) will be included.

“.. substitutions”在第一个文件中是什么意思？

What does ".. substitutions" mean in a rst file?

include

comments

python-sphinx

restructuredtext