我正在尝试使用Sphinx的.. include::指令将一个文件中的文档包括在另一个文件，以避免重复文档的源文本。我包含的部分在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内联中的授权配置设置，如下所示：
.. include:: /configuration.rst
:start-after: start_config-authorization
:end-before: end_config-authorization
问题是包含的文本中的标签会从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定义的链接(而不是authorization.html中包含的副本(。
简单地忽略或静音这些重复标签警告，并期望所有交叉引用都链接到configuration.html，这样安全吗？或者我应该另辟蹊径吗？
有两种方法可以解决此问题：切换到不同的扩展名(*.inc(，或在conf.py中将任何包含文件添加到exclude_patterns。
想要添加我的解决方案：
.. include:: /configuration.inc.rst
然后放入排除项：
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**/*inc.rst']
这允许您保留rst扩展，您只需要用.inc.rst扩展名重命名包含的rst。
我只想补充一点，我认为这是愚蠢的默认行为，应该被视为一个错误，而不是设计：https://github.com/sphinx-doc/sphinx/issues/7697
如果是设计，设计应该改变，因为这似乎是一种非常常见的使用模式，如果你有很多rst并试图在构建输出中解析这些错误，这些无用的警告会淹没实际的语法问题。
忽略安全吗？它仍然是一个警告，但原始内容似乎阻止了包含的标签，所以如果你不时检查它，应该不会太危险。
你是否尝试过将内容放在一个没有标签的文件中，在需要的地方包含此文件，并创建一个有标签的文件，并包含未标记的内容？最后一个文件应该由引用指向。
Ps：我还没有测试过，所以标签后面可能会有一个包含而不是标准内容。