Duplicates in auto-generated documents

[mfncooper]

When using peer imports, autoapi seems to be generating its own duplicates in the files it generates, resulting in "duplicate object description" warnings. The warning message says "use :noindex: for one of them", but the problem is that autoapi is generating all of the relevant files, so it's not possible to do this.

The big problem, of course, isn't the warnings as much as the duplicate documentation that is being generated, making the resulting API docs rather a mess.

A complete (minimal) example follows, with 5 (very small) source files to illustrate the various facets of the problem.

# __init__.py
from .common import *
from .part1 import *
from .part2 import *
from .part3 import *

# common.py
class HandyClass:
    def do_one(self, x):
        print(x)
    def do_two(self, x):
        print(x + x)

# part1.py
from .common import HandyClass

class Part1Class(HandyClass):
    def hello(self):
        self.do_one('part 1')
        print('hello')

# part2.py
from .common import HandyClass

class Part2Class:
    def goodbye(self):
        print('goodbye')

# part3.py
class Part3Class:
    def aloha(self):
        print('aloha')

After creating a docs structure with sphinx-quickstart and adding a minimal autoapi configuration, running make html results in the following warnings in the console (with paths truncated by me for brevity here):

[...]/aatest/docs/source/autoapi/aatest/index.rst:46: WARNING: duplicate object description of aatest.HandyClass, other instance in autoapi/aatest/index, use :noindex: for one of them
[...]/aatest/docs/source/autoapi/aatest/index.rst:48: WARNING: duplicate object description of aatest.HandyClass.do_one, other instance in autoapi/aatest/index, use :noindex: for one of them
[...]/aatest/docs/source/autoapi/aatest/index.rst:51: WARNING: duplicate object description of aatest.HandyClass.do_two, other instance in autoapi/aatest/index, use :noindex: for one of them
[...]/aatest/docs/source/autoapi/aatest/index.rst:63: WARNING: duplicate object description of aatest.HandyClass, other instance in autoapi/aatest/index, use :noindex: for one of them
[...]/aatest/docs/source/autoapi/aatest/index.rst:65: WARNING: duplicate object description of aatest.HandyClass.do_one, other instance in autoapi/aatest/index, use :noindex: for one of them
[...]/aatest/docs/source/autoapi/aatest/index.rst:68: WARNING: duplicate object description of aatest.HandyClass.do_two, other instance in autoapi/aatest/index, use :noindex: for one of them

Notice that there is one "set" of warnings for each source file that imports HandyClass. That is, there are two sets of warnings because part1.py and part2.py both import from .common, but not a third set because part3.py does not. Notice also that, although part2.py imports from .common, it doesn't actually use it, so it's the existence of the import that's causing the issue.

[Conchylicultor]

Yes, the lack of control over duplicate is currently a huge pain point and prevent us to use autoapi.

Also related to:

• Duplicated symbols appear in 2 places #317
• Feature: option to avoid auto-including submodule #339

There could be a few easy fixes to avoid those duplicate like:

• When a __all__ is present in the file, it indicates that the user has explicitly define the public API, so other member not present in __all__ should not be documented.

For example, if we take numpy, according to autoapi authors, sin() should be documented 3 times !!!

np.sin
np.core.sin
np.core.umath.sin

However the numpy authors made it explicit that np.core is NOT part of the public API:

assert 'sin' in np.__all__
assert 'core' not in np.__all__

Currently, sphinx-autoapi violate this very standard Python convention.

[chrisjsewell]

Heya, as mentioned in #287 (comment), I've just created https://sphinx-autodoc2.readthedocs.io/, which handles this, I hope, in a better way: https://sphinx-autodoc2.readthedocs.io/en/latest/quickstart.html#documenting-only-the-public-api-via-all

Happy to have feedback and collaborate on it!

[AWhetter]

This issue is essentially a duplicate of #317, which was closed for this reason (#317 (comment)).
However I think that AutoAPI could be doing a better job of documenting what to do in this situation. I'll continue this discussion on #339.
Note that AutoAPI already respects __all__, so you can use that control what AutoAPI documents and what it doesn't.