Importing classes from subpackages in __init__.py and using automodule gives reference target not found errors

[thomascobb]

Describe the bug
Consider a module which splits classes into their own files and pulls them together in __init__.py. It has a folder structure like this:

project/
    mymodule/
        __init__.py
        _types.py
        _util.py

Where __init__.py looks like this:

from ._types import MyClass
from ._util import my_func
__all__ = ["MyClass", "my_func"]

_types.py looks like this:

class MyClass:
    pass

_util.py looks like this:

from ._types import MyClass

def my_func(inst: MyClass):
    pass

If you document with:

.. automodule:: mymodule
    :members:

Then you get a warning like:

__init__.py:docstring of mymodule.my_func:: WARNING: py:class reference target not found: mymodule._types.MyClass

I guess an alias dictionary of cross-references might help (when automodule encounters mymodule.MyClass, it looks at MyClass.__module__ and registers it as the cross-reference for that too). I'm happy to have a go at fixing this if you can point me at where this alias dictionary might be added.

To Reproduce
Steps to reproduce the behavior:

$ git clone https://github.com/thomascobb/dls_python3_template_module
$ cd dls_python3_template_module
$ pipenv install --dev
$ sphinx-build -E -b html docs build/html
$ firefox build/html/reference/api.html

Expected behavior
The signature of say_hello_lots() should have reference dls_python3_template_module.HelloClass, not dls_python3_template_module._types.HelloClass.

Environment info

• OS: Linux
• Python version: 3.7.5
• Sphinx version: 3.0.1, but also happens with 3.x branch
• Sphinx extensions: sphinx.ext.autodoc, sphinx.ext.napoleon

Additional context
Add any other context about the problem here.

• Functionality added in Close #7341: py domain: type annotations are converted to cross refs #7346
• Workaround suggested in Cross referencing breaks for inherited objects imported and documented in a parent module #3048

[tk0miya]

Thank you for reporting. Indeed, it is the biggest problem for autodoc now. I'm trying to define a canonical name for each python object in #7463.