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

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

Closed
thomascobb opened this issue Apr 16, 2020 · 3 comments

Comments

@thomascobb
Copy link

thomascobb commented Apr 16, 2020

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.

@thomascobb thomascobb changed the title Gathering together classes from subpackages in __init__.py and using automodule gives reference target not found errors Importing classes from subpackages in __init__.py and using automodule gives reference target not found errors Apr 16, 2020
@tk0miya tk0miya added this to the 3.1.0 milestone Apr 17, 2020
@tk0miya
Copy link
Member

tk0miya commented Apr 17, 2020

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.

@tk0miya
Copy link
Member

tk0miya commented Apr 20, 2021

Now Sphinx-v4.0.0b1 can process this correctly. Please try it.
Thanks,

refs: #9026

@tk0miya tk0miya closed this as completed Apr 20, 2021
@thomascobb
Copy link
Author

This fixes it, thanks

altendky added a commit to altendky/qtrio that referenced this issue May 24, 2021
altendky added a commit to altendky/qtrio that referenced this issue May 24, 2021
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 11, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

2 participants