Let autosummary match docs for module made from a single file or made of multiple files

[nabriis]

Is your feature request related to a problem? Please describe. In our current software package we use the really nice recursive feature of autosummary to automatically generate our API docs using the lines (renamed the package name to "package"):

.. autosummary::
   :toctree: _autosummary
   :nosignatures:
   :recursive:

   package

Our commonly used modules are single python files with multiple classes inside them. They show up in the Python CLI and API doc the same way, namely as:

package.module1.Class1
package.module1.Class2
etc.

which is exactly what we want.

However, recently one of our modules got so big we wanted to split it into multiple files using the structure

module1/
    __init__.py
    _class1.py
    _class2.py

In the init.py we add

from ._class1 import Class1
from ._class2 import Class2

__all__ = ['Class1', 'Class2']

In the Python CLI this shows up as before, namely as package.module1.Class1 and package.module1.Class2 when importing the package.

However, for the autosummary the private "modules/files" _class1.py and _class2.py are ignored even if the classes are publicly available through module1 thanks to the init.py file.

If we make the class files public (e.g. class1.py and class2.py) the autosummary will use the full path length for the auto genereted API, namely

package.module1.class1.Class1
package.module1.class2.Class2

which is not what we are looking for.

Describe the solution you'd like It would be very useful if the autosummary could follow the convention of the python package imports and expose the same API as the CLI is exposes. This would mean that in the above case you get the same API doc for a single module file or module split into multiple (private) files.

Describe alternatives you've considered An alternative is to manually add each of the classes we want to document. Namely adding the following lines

.. currentmodule:: package.module1

.. autoclass:: class1
   :members:
   :show-inheritance:

.. autoclass:: class2
   :members:
   :show-inheritance:

provides the current structure even when the classes live in the _class.py files. But this is a much more manual process

Additional context