斯芬克斯的。。include:：指令和“重复标签”警告

Question

我试图使用Sphinx的^{} directive将一个文件中的文档包含到另一个文件中，以避免复制文档的源文本。我要包括的部分在configuration.rst（它是配置设置的参考文档的一部分），它包含了一些用于交叉引用每个配置设置的标签：

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

在另一个文件（authorization.rst）中，我只包含来自configuration.rst内联的授权配置设置，如下所示：

^{pr2}$

问题是，包含文本中的标签会从Sphinx生成以下警告：

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

到目前为止，交叉引用似乎还没有被打破，如果我说：

:ref:`ckan.auth.anon_create_dataset`

在第三个文件中，这将正确地生成到configuration.html中ckan.auth.anon_create_dataset定义的链接（而不是{}中包含的副本）。在

简单地忽略这些重复标签警告或使其静音，并期望所有交叉引用都链接到configuration.html安全吗？或者我应该另找一种方法吗？在

Answer 1

有两种方法可以解决这个问题：切换到不同的扩展名（*.inc），或者将任何包含文件添加到exclude_patterns中的conf.py。在

Answer 2

可以忽略吗？它将仍然是一个警告，但原始内容似乎阻止了包含的标签，因此，如果你不时检查它，它应该不会太危险。在

您是否尝试过将内容放在一个文件中，而不是没有标签的索引，在需要它的任何地方包含此文件，并创建一个带标签的索引文件并包含未标记的内容？最后一个文件应该被引用。在

Ps：我还没有测试过，所以标签后面会有include和非标准内容。在