sphinx 构建上的重复索引警告；如何在不索引文件内容的情况下包含文件? [英] Duplicate index warning on sphinx build; How do I include a file without indexing its contents?

问题描述

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

I wish to create an single_html.rst file that contains all my class/method/attribute/etc... , but also split categorised symbols into seperate pages.

例如

.. single html

.. include:: foo.rst

.. include:: bar.rst

bar.rst

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

foo.rst

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

这会引发多个重复对象描述错误:

/path/to/project/my/mod.py:docstring of my.module.Bar:0: 警告:my.mod.Bar 的重复对象描述，/path/to/project/docs/中的其他实例source/api/single_html.rst，使用 :noindex: 作为其中之一

/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: 警告:my.mod.Foo 的重复对象描述，/path/to/project/docs/中的其他实例source/api/single_html.rst，使用 :noindex: 作为其中之一

/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:: 指令上，因为这会完全删除所有索引.(所以要么有重复的索引，要么根本没有！)

I can't simply place :noindex: on the autoclass:: directives as this will remove all the indexes completely. (so there are either duplicate indexes or none at all!)

有没有更好的方法来做到这一点?

Is there a better way to do this?

推荐答案

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

You can avoid those warnings by changing the extension of included files.

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

Sphinx considers each .rst (by default, it can be changed in the conf.py file) as a "source to parse" file. So it will try to parse the foo.rst and the bar.rst files and find autodoc directives for my.mod.Foo and my.mod.Bar. When it tried to parse single_html.rst, it first include the content of foo.rst and bar.rst; thus, it then find again the directives for my.mod.Foo and my.mod.Bar.

通过将 foo.rst 和 bar.rst 重命名为 foo.inc 和 bar.inc(无论您想要作为扩展名)，您都将阻止 Sphinx 解析包含的文件并避免警告.

By renaming foo.rst and bar.rst to foo.inc and bar.inc (of whatever you want as extension), you will prevent Sphinx from parsing the included files and will avoid the warnings.

这篇关于sphinx 构建上的重复索引警告；如何在不索引文件内容的情况下包含文件?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！