sphinx [tracker] Issues related to autodoc and "undefined reference"

This issue serves as a tracker for issues related to autodoc and its inhability 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

#9813
#11225
#10400

Forward References and `from future import annotations`

#9813
#11327

Type variables and new types treated as `data` instead of `class`

#9705
#9172
#9705
#9980
#11552

`None` and `Optional` not linking correctly:

#9740
#10773
#10899
#11211
#11522

Using optional as keyword misidentified as type:

#11376

`Literal` types not linking correctly:

#9266
#10525
#10794
#11156

`Returns` section types not linking:

#9394

`Yield` section types not linking correctly:

#10982

Generic types not linking:

#10873
#7450

`@dataclass` specific linking bugs:

#10893
#11672

`@property` return type:

#10221
#10396
#8004

General alias linking problems:

#9453
#12286

Napoleon specific:

#8290

Docstring extraction

#12020

Miscellaneous

#7972
#11278
#12472

Under consideration (Python 3.9 failure only)

https://github.com/sphinx-doc/sphinx/issues/11387

Tasks issues

#11687
#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.

Feb 19 '24 10:02 picnixz

These are the issue I could find that relate to types not linking correctly where the cause is plain processing of annotations in signatures or docstrings.

`None` and `Optional` not linking correctly:

#9740
#10773
#10899
#11211
#11522

Using optional as keyword misidentified as type:

#11376

`Literal` types not linking correctly:

#9266
#10525
#10794
#11156

`Returns` section types not linking:

#9394

`Yield` section types not linking correctly:

#10982

Generic types not linking:

#10873

Alias of generic and parameterized types:

#7450

`TypeVar` not linking:

#9172
#9705
#9980

`TYPE_CHECKING` specific:

#10400

`@dataclass` specific linking bugs:

#10893
#11672

`@property` return type:

#10221
#10396

(maybe a regression of the older - #8004)

autodoc mixing up data types:

#11552

this issue is somewhat of a miscellaneous:

#7972

General alias linking problems:

#9453

Napoleon specific:

#8290

Feb 21 '24 07:02 electric-coder

Thank you for what you found. I'll update my issue tomorrow.

EDIT: I've included your issues in mine so I'll hide your comment. Thank you!

Feb 23 '24 19:02 picnixz

sphinx sphinx copied to clipboard

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

TYPE_CHECKING guarded imports

Forward References and from __future__ import annotations

Type variables and new types treated as data instead of class

None and Optional not linking correctly:

Using optional as keyword misidentified as type:

Literal types not linking correctly:

Returns section types not linking:

Yield section types not linking correctly:

Generic types not linking:

@dataclass specific linking bugs:

@property return type:

General alias linking problems:

Napoleon specific:

Docstring extraction

Miscellaneous

Under consideration (Python 3.9 failure only)

Tasks issues

Possible solutions

None and Optional not linking correctly:

Using optional as keyword misidentified as type:

Literal types not linking correctly:

Returns section types not linking:

Yield section types not linking correctly:

Generic types not linking:

Alias of generic and parameterized types:

TypeVar not linking:

TYPE_CHECKING specific:

@dataclass specific linking bugs:

@property return type:

autodoc mixing up data types:

General alias linking problems:

Napoleon specific:

sphinx
sphinx copied to clipboard

`TYPE_CHECKING` guarded imports

Forward References and `from future import annotations`

Type variables and new types treated as `data` instead of `class`

`None` and `Optional` not linking correctly:

`Literal` types not linking correctly:

`Returns` section types not linking:

`Yield` section types not linking correctly:

`@dataclass` specific linking bugs:

`@property` return type:

`None` and `Optional` not linking correctly:

`Literal` types not linking correctly:

`Returns` section types not linking:

`Yield` section types not linking correctly:

`TypeVar` not linking:

`TYPE_CHECKING` specific:

`@dataclass` specific linking bugs:

`@property` return type: