摆脱 Sphinx 中的 "duplicate label" 警告

Question

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

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

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

如何摆脱所有这些警告？是否应该将它们静音，或者是否有您应该使用的不同切片方式？

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

中的标签“gamepad”

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

Answer 1

问题是我们仍在使用已弃用的 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 2

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

Answer 3

As recommonmark is deprecated, use myst-parser 改为：

pip install --upgrade myst-parser

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

尽管使用该设置，我仍然收到相同的重复标签警告。结果我必须从我的 extensions 列表中删除 'sphinx.ext.autosectionlabel' 才能解决问题。

摆脱 Sphinx 中的 "duplicate label" 警告

Get rid of "duplicate label" warning in Sphinx

markdown

restructuredtext

python-sphinx

commonmark