CODEWITHSUNDEEP
pythonpython-sphinx
Sean Hammond
Sean Hammond

Reputation: 14590

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

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?

Upvotes: 18

Views: 6196

Answers (3)

red888
red888

Reputation: 31570

Want to add my solution to this:

.. include:: /configuration.inc.rst

Then glob in exclusions:

exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**/*inc.rst']

This allows you to keep the rst extension, you just need to rename the included rsts with a .inc.rst extension.

I'll just add, I think this is dumb default behavior and should be considered a bug not by design: https://github.com/sphinx-doc/sphinx/issues/7697

If it's by design the design should change because this seems to be a really common usage pattern and these useless warnings drown out actual syntax issues if you have a lot of rsts and are trying to parse through this in the build output.

Upvotes: 1

jhermann
jhermann

Reputation: 2101

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

Upvotes: 14

martinqt
martinqt

Reputation: 719

Safe to ignore? It will remain a warning but the original content seems to block the included labels so it shouldn't be too dangerous if you check it from time to time.

Have you tried putting the content in a file, not indexed with no label, include this file wherever you need it and create a file, indexed, with the label and include the unlabeled content? The last file should be pointed by references.

Ps: I haven't tested so the label might get crossed by the fact it's followed by an include and not standard content.

Upvotes: -1

Related Questions