sphinx-doc/sphinx

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

Open

#11,991 opened on Feb 19, 2024

View on GitHub
 (4 comments) (10 reactions) (0 assignees)Python (5,625 stars) (1,985 forks)batch import
extensions:autodochelp wantedinternals:other

Description

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

  • #9813
  • #11225
  • #10400
  • #13137

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

Undefined references to pathlib.Path and co.

  • #13178

None and Optional not linking correctly:

  • #9740
  • #10773
  • #10793
  • #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)

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.

Contributor guide

Tech stack
python
Domain
documentation
Issue type
research
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
over 1 week
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
Familiarity with Sphinx autodocUnderstanding of Python type annotations
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
20
Research direction
This is a tracker issue compiling many related bugs in Sphinx's autodoc extension regarding undefined references in type annotations. The issue lists sub issues across categories like TYPE CHECKING guarded imports, forward references, and generic types. A good starting point is to examine one of the linked sub issues, such as #9813 about TYPE CHECKING, to understand the root cause. Look at the existing discussion and any attempted fixes in those sub issues to identify patterns.