sphinx构建上的重复索引警告;如何在不对其内容编制索引的情况下包含文件？

Question

我希望创建一个single_html.rst文件，其中包含我的所有class / method / attribute / etc ...，但也会将分类符号拆分为单独的页面。

e.g。

single_html.rst

.. single html

.. include:: foo.rst

.. include:: bar.rst

bar.rst

.. autoclass:: my.mod.Bar
    :members:

foo.rst

.. autoclass:: my.mod.Foo
    :members:

这会引发多个duplicate object description错误：

  my.module.Bar:0的

/path/to/project/my/mod.py:docstring：警告：my.mod.Bar的重复对象描述，/ path / to / project / docs /中的其他实例source / api / single_html.rst，使用：noindex：用于其中一个

     my.module.Bar:0的

/path/to/project/my/mod.py:docstring：警告：my.mod.Foo的重复对象描述，/ path / to / project / docs /中的其他实例source / api / single_html.rst，使用：noindex：用于其中一个

我不能简单地将:noindex:放在autoclass::指令上，因为这会完全删除所有索引。 （所以有重复索引或根本没有索引！）

有更好的方法吗？

Answer 1

您可以通过更改包含文件的扩展名来避免这些警告。

Sphinx将每个.rst（默认情况下，可以在conf.py文件中更改）视为“解析源”文件。因此，它会尝试解析foo.rst和bar.rst文件，并找到autodoc和my.mod.Foo的{​​{1}}指令。 在尝试解析my.mod.Bar时，它首先包含single_html.rst和foo.rst的内容;因此，它再次找到bar.rst和my.mod.Foo的指令。

通过将my.mod.Bar和foo.rst重命名为bar.rst和foo.inc（任何您想要的扩展名），您将阻止Sphinx解析所包含的文件并避免警告。