Summary

Add smarts to autodoc_utils for inherited TypedDicts.

Review Request #14480 — Created June 27, 2025 and submitted July 7, 2025, 3:29 p.m.

Information

Owner

david

Repository

beanbag-docutils

Branch

master

Bugs

Depends On

Reviewers

Groups

beanbag-misc

People

Description

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.

Commits

Summary	ID
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

Summary

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

Issues

Description	From	Last Updated
Let's make autodoc_utils a literal.	chipx86	July 3, 2025, 9:41 a.m.
Missing the ending __ on __orig_bases__	maubin	July 3, 2025, 9:41 a.m.
Should say "versions" or "an older version" here instead of just of "version"	maubin	July 3, 2025, 9:41 a.m.
"for" or "from"?	chipx86	July 3, 2025, 9:41 a.m.
This requires 3.9+. That might be fine but it'd be nice to keep this module a bit wider in terms …	chipx86	July 3, 2025, 9:42 a.m.
Should we use Sequence instead of list?	chipx86	July 3, 2025, 9:42 a.m.
We access self.object 3 times outside the loop and every iteration within the loop where there's a docstring. Let's pull …	chipx86	July 3, 2025, 9:42 a.m.
Should this be a Sequence?	chipx86	July 3, 2025, 9:43 a.m.
Missing a period.	chipx86	July 3, 2025, 9:43 a.m.
Missing a period.	chipx86	July 3, 2025, 9:43 a.m.
Can we use obj instead, so we're not stomping on object?	chipx86	July 7, 2025, 3:04 p.m.

flake8 passed.

JSHint passed.

Ship it!

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Missing the ending __ on __orig_bases__
```
beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Should say "versions" or "an older version" here instead of just of "version"
```

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Let's make autodoc_utils a literal.
```
beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 1)
The issue has been dropped. Show all issues
```
"for" or "from"?
```
1. david July 3, 2025, 9:44 a.m.
  for. The docstrings are coming from parent classes, not the inherited classes.

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 1)

The issue has been resolved. Show all issues

This requires 3.9+. That might be fine but it'd be nice to keep this module a bit wider in terms of Python compatibility so we can more easily continue to build docs for older (but still recent) products and deal with any issues that come up.

Can we keep this a standard dict and move the typing into the annotation?

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 1)
The issue has been dropped. Show all issues
```
Should we use Sequence instead of list?
```
1. david July 3, 2025, 9:44 a.m.
  This needs to match the parent class signature.

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 1)

The issue has been resolved. Show all issues

We access self.object 3 times outside the loop and every iteration within the loop where there's a docstring. Let's pull it out.

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Should this be a Sequence?
```
beanbag_docutils/sphinx/ext/tests/test_autodoc_utils.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Missing a period.
```
beanbag_docutils/sphinx/ext/tests/test_autodoc_utils.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Missing a period.
```

Commits:

	Summary	ID
	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.	d03ed7800aac3ddc90863ee8335360382d40ab11
	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

Diff:

Revision 2 (+506 -4)

Show changes

	beanbag_docutils/sphinx/ext/autodoc_utils.py
	beanbag_docutils/sphinx/ext/tests/test_autodoc_utils.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Looks good. One nit.
```
beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 2)
The issue has been resolved. Show all issues
```
Can we use obj instead, so we're not stomping on object?
```

Status:: Completed
Change Summary:: Pushed to master (fc1ce2d)