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

python, python-sphinx

Solution

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

Problem

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?

Original source