python-sphinx - sphinx 构建上的重复索引警告；如何在不索引文件内容的情况下包含文件？

Question

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

例如

single_html.rst

.. single html

.. include:: foo.rst

.. include:: bar.rst

酒吧.rst

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

第一步

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

这会抛出多个 duplicate object description错误:

/path/to/project/my/mod.py:docstring of my.module.Bar:0: WARNING: duplicate object description of my.mod.Bar, other instance in /path/to/project/docs/source/api/single_html.rst, use :noindex: for one of them

/path/to/project/my/mod.py:docstring of my.module.Bar:0: WARNING: duplicate object description of my.mod.Foo, other instance in /path/to/project/docs/source/api/single_html.rst, use :noindex: for one of them

我不能简单地放置 :noindex:在 autoclass::指令，因为这将完全删除所有索引。 (所以要么有重复的索引，要么根本没有!)

有一个更好的方法吗？

Answer 1

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

Sphinx 考虑每个 .rst (默认情况下，它可以在 conf.py 文件中更改)作为“要解析的源”文件。所以它会尝试解析 foo.rst和 bar.rst文件并查找 autodoc my.mod.Foo 的指令和 my.mod.Bar .
当它试图解析 single_html.rst , 它首先包含 foo.rst 的内容和 bar.rst ;因此，它然后再次找到 my.mod.Foo 的指令和 my.mod.Bar .

通过重命名 foo.rst和 bar.rst至 foo.inc和 bar.inc (任何你想要的扩展名)，你将阻止 Sphinx 解析包含的文件并避免警告。