autodoc: Handling of "forward references" for typed functions/methods

[chrisjsewell]

Describe the bug

If a function/method/etc is typed with an object from another module in the package, this can lead to the reference to that object not yet being available, and thus the referencing fails.

To Reproduce

Create a python module in a package with an object:

package/other.py:

class MyClass:
   pass

create another module that references that object as a type:

package/main.py:

from .other import MyClass

def func(klass: MyClass) -> None:
   pass 

Then I guess dependent on the order of file parsing / syntax tree assessment, this can lead to:

package/main.py:docstring of package.main.func::py:class reference target not found: package.other.MyClass

Expected behavior

The reference for the type should be found.

Your project

I've encountered this in numerous projects, but most recently in aiidateam/aiida-core#4575

/Users/workuser/Codes/aiida-core/aiida/tools/graph/graph_traversers.py:docstring of aiida.tools.graph.graph_traversers.TraverseGraphOutput.links::py:class reference target not found: aiida.orm.utils.links.LinkQuadruple

Environment info

• OS: Unix (any)
• Python version: 3.8
• Sphinx version: 3.2.1
• Sphinx extensions: sphinx.ext.autodoc

[tk0miya]

Is package.other.MyClass documented? If not, Sphinx can't resolve the reference. Please add it to your document.

[tk0miya]

Now I'm closing this. Please feel free to reopen if you're still in trouble.
Thanks,

[ltalirz]

yes, I believe this occurs also in cases where package.other.MyClass is documented.
Would it help if @chrisjsewell created a repository with a minimum working example to reproduce this?

[tk0miya]

Yes. It must be helpful!