Sphinx的.. include :: directive和"重复标签"警告

Question

我正在尝试使用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`

在第三个文件中,这正确地生成了一个到ckan.auth.anon_create_datasetin 的定义的链接configuration.html(而不是它的包含副本authorization.html).

简单地忽略或消除这些重复标签警告是否安全,并期望所有交叉引用链接到configuration.html？或者我应该找到另一种方法吗？

Answer 1

有两种方法来解决这个问题:切换到不同的扩展名(*.公司),或添加任何包含文件exclude_patterns在conf.py.

Answer 2

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

您是否尝试过将内容放入一个文件中，没有索引，没有标签，在任何需要的地方包含该文件，并创建一个文件，索引，带有标签并包含未标记的内容？最后一个文件应该由参考文献指出。

Ps：我还没有测试过，因此标签可能会因为它后面跟着包含内容而不是标准内容而被交叉。