狮身人面像。包括：：指令和重复标签&q；警告 [英] Sphinx's .. include:: directive and "duplicate label" warnings

问题描述

我正在尝试使用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是否安全？或者我应该找到另一种方法来做这件事？

推荐答案

有两种方法可以解决此问题：切换到其他扩展名(*.inc)，或将任何包含文件添加到conf.py中的exclude_patterns。

这篇关于狮身人面像。包括：：指令和重复标签&q；警告的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！