摆脱 Sphinx 中的“重复标签”警告

Question

在 Sphinx 中，我收到大量警告，例如：

/PATH/FILENAME:LINE: WARNING: duplicate label LABELNAME, other instance in /PATH/FILENAME

似乎将所有节标题视为“标签”，并且有一堆节标题在多个文件中使用。 例如，我们每个版本的每个发行说明都有一页，并且每个版本都有“改进”和“修复”。

如何摆脱所有这些警告？他们应该被静音，还是有其他你应该使用的切片方法？

一个例子是 desktop.rst 和 vr-controls.rst

中的标签“gamepad”

作为参考，我们仍然使用Sphinx 2.4.4 我在变更日志中没有看到任何看似相关的内容。

Answer 1

由于

recommonmark

已被弃用，请使用

myst-parser

代替：

pip install --upgrade myst-parser

# and inside conf.py:
extensions = ['myst_parser', ...]

尽管采用了这种设置，我仍然有相同的重复标签警告。结果我必须从我的

'sphinx.ext.autosectionlabel'

列表中删除

extensions

才能解决问题。

Answer 2

问题是我们仍然使用已弃用的 conf.py 选项来进行重新标记。 我们仍然按照 recommonmark.readthedocs.io/en/latest/ 使用 Sphinx-1.3 及更早版本的选项 改变

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

到

extensions = ['recommonmark']

解决了问题。

非常感谢@StevePiercy 让我意识到我们已弃用的配置。

Answer 3

看起来 sphinx 解析器会解析文件夹中的每个 .rst 文件以创建 HTML。当其中一些 .rst 文件包含在 main.rst 中时，我们似乎收到了重复的标签消息。为了帮助解析器不解析这些包含内容，您可以尝试将扩展名从 .rst 更改为其他名称，例如 .rest，然后这些消息就会消失。确保现在包含的文件包含具有新文件扩展名的文件，例如前面提到的 .rest

Answer 4

正如其他人提到的，

sphinx.ext.autosectionlabel

正在产生这些警告。我遇到了同样的问题，并通过添加来减少警告数量

suppress_warnings = ['autosectionlabel.*']

在

conf.py

文件中。我还剩下一些警告（可能是原始数量的 20%），我必须对其进行调查，但我认为分享这些警告会很有用。链接到文档：suppress_warnings。