15

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

在第三个文件中，这会正确生成指向 in 定义的链接ckan.auth.anon_create_dataset（configuration.html而不是 in 的包含副本authorization.html）。

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

4

2 回答 2

13

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

于 2016-02-21T20:41:37.330 回答
-1

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

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

Ps：我还没有测试过，所以标签可能会被它后面是包含而不是标准内容的事实所越过。

于 2013-04-28T13:10:13.757 回答