Duplicate index warning on sphinx build; How do I include a file without indexing its contents?

Question

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.

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:

This throws multiple duplicate object description errors:

/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

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?

Answer 1

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

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.

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.