Sphinx's .. include:: directive and "duplicate label" warnings

Question

I'm trying to use Sphinx's .. include:: directive to include docs from one file in another file, to avoid duplicating the source text of the docs. The section I'm including is in configuration.rst (it's part of the reference docs for the config settings) and it contains some labels for cross-referencing each config setting:

.. start_config-authorization

.. _ckan.auth.anon_create_dataset:

ckan.auth.anon_create_dataset
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Example::

 ckan.auth.anon_create_dataset = False

Default value: ``False``

Allow users to create datasets without registering and logging in.


.. _ckan.auth.create_unowned_dataset:

ckan.auth.create_unowned_dataset
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

...

.. end_config-authorization

In another file (authorization.rst) I include just the authorization config settings from configuration.rst inline, like this:

.. include:: /configuration.rst
    :start-after: start_config-authorization
    :end-before: end_config-authorization

The problem is that the labels within the included text produce this warning from Sphinx:

doc/configuration.rst:224: WARNING: duplicate label ckan.auth.anon_create_dataset, other instance in doc/authorization.rst

So far cross-referencing doesn't seem to be broken, if I put:

:ref:`ckan.auth.anon_create_dataset`

in a third file, this correctly produces a link to the definition of ckan.auth.anon_create_dataset in configuration.html (and not the included copy of it in authorization.html).

Is it safe to simply ignore or silence these duplicate label warnings, and expect all cross-refs to link to configuration.html? Or should I find another way of doing this?

Answer 1

There are two ways to solve this: switch to a different extension (*.inc), or add any include files to exclude_patterns in conf.py.