Skip to content

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

Open
5 of 40 issues completed
Open
@picnixz

Description

@picnixz

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

Forward References and from __future__ import annotations

Type variables and new types treated as data instead of class

Undefined references to pathlib.Path and co.

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

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.

Sub-issues

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions