Search code examples
markdownpython-sphinxrestructuredtextcommonmark

Get rid of "duplicate label" warning in Sphinx

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.

Solution

  • 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.