python - Sphinx 的 .. include::directive 和 "duplicate label"警告

Question

我正在尝试使用 Sphinx的 .. include:: 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 内联的授权配置设置，如下所示:

.. 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 是否安全？或者我应该找到另一种方法吗？

Answer 1

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