Closed mfncooper closed 1 year ago
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:
__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.
Heya, as mentioned in https://github.com/readthedocs/sphinx-autoapi/issues/287#issuecomment-1435045134, 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!
This issue is essentially a duplicate of #317, which was closed for this reason (https://github.com/readthedocs/sphinx-autoapi/issues/317#issuecomment-1033316693).
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.
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.
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):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.