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

【问题标题】：Get rid of "duplicate label" warning in Sphinx摆脱 Sphinx 中的“重复标签”警告
【发布时间】：2020-06-29 04:45:53
【问题描述】：

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

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

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

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

一个例子是desktop.rst和vr-controls.rst中的标签“gamepad”

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

【问题讨论】：

请编辑您的问题以包含导致这些警告的 reST 示例。我无法在 Pyramid 的文档 Change History 中复制此问题。
@StevePiercy 我们实际上混合使用了 rst 和 commonMarkup。我为两个 rst 文件发生的问题添加了一个示例。但是，commonMarkup 文件也会出现同样的问题。
使用 Sphinx 2.3.1，我尝试将您的两个页面添加到单个文件文档中，并且构建得很好（当然，除了缺少图像和 unknown document: ../interact）。但是，当我克隆您的存储库并尝试构建文档时，我看到了警告。首先，我根据recommonmark.readthedocs.io/en/latest 将conf.py 更改为Sphinx 1.4+。除此之外，我不知道，因为我不使用recommonmark。我想问题在于 .rst 和 .md 的使用，而不仅仅是一种语法。我建议选择一个。
@StevePiercy 根据推荐文档修复 conf.py 实际上完全解决了问题。非常感谢！我不认为我自己会发现这一点。
我看到了同样的警告，因为在一个不使用 recommonmark 的项目中存在同样的问题 :-(

标签： markdown python-sphinx restructuredtext commonmark

【解决方案1】：

问题是我们仍在使用已弃用的 conf.py 选项作为 recommonmark。根据recommonmark.readthedocs.io/en/latest/，我们仍在使用 Sphinx-1.3 及更早版本的选项改变

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

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

到

extensions = ['recommonmark']

修复了问题。

非常感谢 @StevePiercy 让我了解我们已弃用的配置。

【讨论】：

【解决方案2】：

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

【讨论】：

【解决方案3】：

As recommonmark is deprecated，改用myst-parser：

pip install --upgrade myst-parser

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

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

【讨论】：