Get rid of "duplicate label" warning in Sphinx

Question

In Sphinx I get a ton of warnings like:

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

It seems to see all section titles as "label"s and there is a bunch of section titles that are used in multiple files. For example we have a one page per release note per version, and in every version there is "Improvements" and "Fixes".

How would one get rid of all of these warnings? Should they just be silenced, or is there a different way for sectioning that you are supposed to use?

One example is the label "gamepad" in desktop.rst and vr-controls.rst

For reference, we still use Sphinx 2.4.4 I haven't seen anything in the changelogs that seemed related.

Answer 1

The issue was us still using a deprecated conf.py option for recommonmark. We were still using the option for Sphinx-1.3 and earlier as per recommonmark.readthedocs.io/en/latest/ Changing

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

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

to

extensions = ['recommonmark']

fixed the issue.

Big thanks to @StevePiercy for making me aware of our deprecated config.

Answer 2

As recommonmark is deprecated, use myst-parser instead:

pip install --upgrade myst-parser

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

Though with that setup, I still had the same duplicate label warnings. Turns out I had to remove 'sphinx.ext.autosectionlabel' from my extensions list to resolve the problem.

Answer 3

It looks like the sphinx parser parses every .rst file in the folder to create a HTML. When some of these .rst files are included in the main.rst it looks like we are getting this duplicate label messages. To help the parser from not parsing these includes you can try changing the extension from .rst to something else like .rest and then these messages are gone. Make sure that the include now includes the files with the new file extension like .rest as called out before