Add smarts to autodoc_utils for inherited TypedDicts.

Review Request #14480 — Created June 27, 2025 and submitted — Latest diff uploaded

Information

beanbag-docutils
master

Reviewers

TypedDict inheritance is weird in a way that Sphinx can't deal with
easily. TypedDict isn't actually a class itself, and things which
inherit from it get flattened to inherit directly from dict and have a
variety of annotation-only properties for the data inside. Sphinx can
find any documentation attached to those properties, but when one
inherits from another, the documentation for any properties coming from
the parent class gets lost.

This change adds some custom documenter classes to detect when we have
inherited TypedDict members and to scan up the chain using
__orig_bases__ to find docs for inherited members.

This requires Python 3.11+ if using typing.TypedDict. It works for all
versions when using typing_extensions.TypedDict.

  • Built the RBTools documentation with this and saw that all of our new
    *Params definitions had documentation for all members, including ones
    inherited from parent classes.
  • Ran unit tests.

Diff Revision 2 (Latest)

orig
1
2

Commits

First Last Summary ID Author
Add smarts to autodoc_utils for inherited TypedDicts.
`TypedDict` inheritance is weird in a way that Sphinx can't deal with easily. `TypedDict` isn't actually a class itself, and things which inherit from it get flattened to inherit directly from `dict` and have a variety of annotation-only properties for the data inside. Sphinx can find any documentation attached to those properties, but when one inherits from another, the documentation for any properties coming from the parent class gets lost. This change adds some custom documenter classes to detect when we have inherited TypedDict members and to scan up the chain using `__orig_bases__` to find docs for inherited members. This requires Python 3.11+ if using `typing.TypedDict`. It works for all versions when using `typing_extensions.TypedDict`. Testing Done: - Built the RBTools documentation with this and saw that all of our new `*Params` definitions had documentation for all members, including ones inherited from parent classes. - Ran unit tests.
e7869c4db5a0ffdc3b135721c9f997f5a0ac088f David Trowbridge
beanbag_docutils/sphinx/ext/autodoc_utils.py
beanbag_docutils/sphinx/ext/tests/test_autodoc_utils.py
Loading...