Feature: option to avoid auto-including submodule

[abey79]

Issue

As per the doc, autoapi will "document anything that is publicly accessible". This includes submodules. However, it's a common implementation pattern to have submodules containing implementation details and having all of the "public" API explicitly imported in the __init__.py file.

For example:

>>> hierarchy:

my_package
├ __init__.py
└ core.py
└ utils.py

>>> __init__.py:

# public API
from .core import CoreClass, core_function
from .utils import this_function_is_useful_to_others

For such a package, only the content of __init__.py should be documented, but not the my_package.core and my_package.utils sub-modules. However, there is currently no option (that I am aware of) to disable auto-documenting the sub-module. I propose that such an option should be added.

Workaround

I currently know of two workarounds.

1. Prefix submodules' filenames with _. This is admittedly the Pythonic way to proceed, since it indicates that said sub-modules are not public. autoapi correctly honours this.

2. Setup a autoapi-skip-member filter:

def skip_submodules(app, what, name, obj, skip, options):
    if what == "module":
        skip = True
    return skip


def setup(sphinx):
    sphinx.connect("autoapi-skip-member", skip_submodules)

Discussion

I understand (though I disagree) that workaround (1) above is a strong ground for the rejection of this proposal. I still think that the base pattern is common enough that an option would be beneficial. Alternatively, I at least suggest to add prominent discussion of this issue such as to reduce the friction for new-comers (which, which Sphinx stuff, is already rather high overall).

[Conchylicultor]

+1, related to: #317 (comment)

autoapi should respect the Public API explicitly defined in __all__, as this is the standard way on specifying which symbols are public or not. _prexix only specify private modules at the file level, but not at the package level.

For example, if we take numpy, according to the 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__

So sphinx-autoapi seems to violate this very standard Python convention.

[AWhetter]

I understand (though I disagree) that workaround (1) above is a strong ground for the rejection of this proposal.

I agree. The pattern you've described of having public submodules is a valid and common use case, and therefore AutoAPI should cater to it.

I still think that the base pattern is common enough that an option would be beneficial.

While I agree that an option would be useful for this specific use case, I don't want there to be more ways for AutoAPI to decide what modules should be documented and which shouldn't. That's confusing for users and hard to implement. Instead I think it should be sufficient to document workaround 2 as the solution to this problem for users. More generally, AutoAPI needs to do a better job of documenting how to control what gets documented and what doesn't. So that's the solution I'll be aiming for to address this issue.

Also note that AutoAPI already respects __all__, so you can use that control what AutoAPI documents and what it doesn't.