狮身人面像构建时出现重复索引警告；如何包含文件而不索引其内容？

Question

我希望创建一个single_html.rst包含我所有class/ method/ attribute/ etc ...的文件，而且还要将分类的符号拆分为单独的页面。

例如

single_html.rst

.. single html

.. include:: foo.rst

.. include:: bar.rst

巴斯特

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

foo.rst

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

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

/path/to/project/my/mod.py:my.module.Bar:0的文档字符串：警告：my.mod.Bar的对象描述重复，/ path / to / project / docs / source / api中的其他实例/single_html.rst，对其中之一使用：noindex：

/path/to/project/my/mod.py:my.module.Bar:0的文档字符串：警告：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.Foomy.mod.Barsingle_html.rstfoo.rstbar.rstmy.mod.Foomy.mod.Bar

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