Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Duplicates in auto-generated documents #358

Closed
mfncooper opened this issue Nov 3, 2022 · 3 comments
Closed

Duplicates in auto-generated documents #358

mfncooper opened this issue Nov 3, 2022 · 3 comments

Comments

@mfncooper
Copy link

mfncooper commented Nov 3, 2022

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
Copy link

Conchylicultor commented Nov 11, 2022

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

Also related to:

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
Copy link

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
Copy link
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants