sphinx-doc/sphinx

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

Open

#11,991 opened on 2024年2月19日

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

説明

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.

コントリビューターガイド

技術スタック
python
領域
documentation
Issue 種別
research
難度新しい貢献者にとっての実装難度です。1 は非常に小さな変更、5 は専門的な作業です。
3
推定時間経験ある貢献者が調査、実装、テスト、pull request 準備にかけるおおよその時間範囲です。
over 1 week
活動状況Issue が今どれだけ取り組みやすいかを示します。新しい、活発、古い、ブロック中、またはメンテナー入力待ちなどです。
active
明確さ期待される変更、受け入れ条件、次の手順がどれだけ明確かを示します。
mostly clear
前提条件
Familiarity with Sphinx autodocUnderstanding of Python type annotations
初心者向け度初回貢献者にどれだけ取り組みやすいかを 1-100 で推定したスコアです。
20
調査方針
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.