Sphinx 警告：“重复的替换定义名称” - 错误在哪里？

Question

当我构建 Sphinx 项目时，我遇到了一系列类似这样的错误 - 三次：

content/swdocs.rsts:6: WARNING: Duplicate substitution definition name: "copy".

sdwocs.rsts 包含通用定义。我将其包含在我的文档树中的每个 ReStructuredText 文件中。

文档树中的许多文件都包含其他 RST 文件，但这些文件不应该包含 swdocs.rsts，因为它们实际上是已包含它的文件的一部分。 这个方案出了点问题——可能是一个包含的 RST 文件，其中包含它自己的 swdocs.rsts 副本——但是哪里出了问题？该消息没有给我任何线索。

我尝试通过查看可能存在错误的每个文件来以困难的方式找到错误，但我什么也没发现。大概是我对问题的分析出了问题，它隐藏在“不可能”的某个地方或某种形式中……但是如果没有更多信息，我就陷入了困境。

如何摆脱困境？

Answer 1

.. include::

包含“第一个”文件会将文件文本插入到输入流中，然后继续解析。对于解析器来说，替换定义是直接在文件中还是在包含的文件中并不重要。

Sphinx 将所有输入文件合并到一个公共的“文档树”中。 “替换”命名空间是文档树范围的。

由于这两个功能并在每个 ReStructuredText 文件中包含

swdocs.rsts

，该文档包含冲突的替换定义 （参见

如何定义文件本地替换指令？

） 您可以考虑将替换定义移至

rst_prolog

。