[tracker] Issues related to autodoc and "undefined reference" #11991

This issue serves as a tracker for issues related to autodoc and its inability to render types. Feel free to dump the issues you find relevant and I'll add them to this tracker. That way, people can easily find them and we can also find what is missing or not.

TYPE_CHECKING guarded imports

• Type hints are irregularly documented (+link generation broken) #9813
• Autodoc does not support if TYPE_CHECKING imports #11225
• More than one target found for cross-reference with quotes around type annotation #10400
• automodule does not work with TYPE_CHECKING guarded code #13137

Forward References and from __future__ import annotations

• Type hints are irregularly documented (+link generation broken) #9813
• Autodoc has trouble with type hinting generics and class name forward references #11327

Type variables and new types treated as data instead of class

• Autodoc parameter types in parameter list not resolving for TypeVar or aliases #9705
• References to TypeVars are not resolved when using autodoc_typehints = "description" #9172
• Autodoc parameter types in parameter list not resolving for TypeVar or aliases #9705
• TypeVar objects not documenting as expected #9980
• autosummary generation considers NewType instances to be data, but autodoc considers them a class #11552

Undefined references to pathlib.Path and co.

• References to pathlib objects are incorrectly picked up by autodoc #13178

None and Optional not linking correctly:

• Use aliases in parameter type annotations where they are available #9740
• Option for display mode of Optional[Union]. #10773
• Intersphinx: Create link for Optional in description even if it is an inherited docstring #10793
• py domain: None is no longer hyperlinked after 4.4.0 #10899
• PEP 604 Syntax Fails on Imported Types with Automock Imports #11211
• Inconsistent output for optional parameters/attributes #11522

Using optional as keyword misidentified as type:

• Google style docstrings throw warning target not found: optional #11376

Literal types not linking correctly:

• autodoc does not generate correct reStructuredText when type hints contain special characters #9266
• autodoc_type_aliases not working with typing.Literal type aliases... #10525
• sphinx.ext.autodoc: Typehints, aliases, and (internal/external) cross-references #10794
• py domain markup w/ typing annotations with Literal[] and non \w characters doesn't render #11156

Returns section types not linking:

• Multiple return types aren't hyperlinked #9394

Yield section types not linking correctly:

• Docstring section Yield type doesn't hyperlink in napoleon  #10982

Generic types not linking:

• tuple with generic parameter not correctly documented with autodoc_typehints = 'description' (result of signature is ok) #10873
• autoclass does not work for concrete aliases of a generic type #7450

@dataclass specific linking bugs:

• Dataclass field types are not rendered when factories are used #10893
• Docs from dataclass descriptor fields #11672

@property return type:

• Issue documenting decorators that return classes. #10221
• autodoc-process-signature does not populate return signature for properties #10396
• Return type for Yield attribute not properly hyperlinked in apidocs #8004

General alias linking problems:

• Make default_role aware of aliases. #9453
• [autodoc] undefined reference for aliased type annotation in the class constructor #12286

Napoleon specific:

• Return type does not get linked if napoleon_use_rtype = True #8290

Docstring extraction

• Imported string constant has wrong docstring of str #12020

Miscellaneous

• Inconsistent type references when using autodoc #7972
• [BUG] singledispatch classmethods are not detected by MethodDocumenter #11278
• autodoc_typehints cause bogus Return type sections to be generated in autoclass #12472

Under consideration (Python 3.9 failure only)

• Autodoc - things are messed up for inherited members when using annotations #11387

Tasks issues

• [tracker] Improvement of autodoc_type_aliases #11687
• [tracker] Improvement of ModuleAnalyzer #11688

Possible solutions

For people that want some solutions:

• Consider using autodoc_type_aliases (the support is limited and does not work for missing references in class signatures for instance).
• Ignore the warnings by specifying entries in nitpick_ignore (it does not solve everything but at least you know what is wrong). Be careful though since sometimes names are incorrectly resolved because they are thought to be the same... (e.g., importing docutils.nodes.Node and _pytest.nodes.Node as Node and using Node in an annotation uses the first reference it finds if Node is not available at runtime, e.g., guarded in a TYPE_CHECKING block).
• Maybe try sphinx-autodoc2 or sphinx-autodoc-typehints.