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?
有两种方法可以解决此问题：切换到其他扩展名（* .inc），或将任何包含文件添加到conf.py exclude_patterns 。
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.
链接地址: http://www.djcxy.com/p/13166.html上一篇: 随机化整数行为