Use autodoc-process-bases to substitute TypeVars for their bounds in base classes in docs
#734
Labels
wontfix
This will not be worked on
Comments
tp832944
added
enhancement
tm91236
added a commit
that referenced
this issue
Mar 31, 2025
By removing the `typehints_formatter` we are able to resolve issues #570 and #734. The former issue is resolved by removing the non-picklable function, which enables build caching, and the second is solved by removing the `TypeVar` bound replacement. While the `TypeVar` replacement does provide more concise documentation, it removes a key piece of information, which the reader must be aware of. For example, in: ```python T = TypeVar("T", bound=Data) def typevar(a: T, b: T) -> None: ... def bound(a: Data, b: Data): ... def valid(a: SupervisedData, b: SupervisedData): ... def invalid(a: Data, b: SupervisedData): ... ``` the `typevar` function is the actual specification, `bound` is the documented specification, `valid` is a valid specification, and `invalid` is an invalid specification which is presented as valid in the documentation (if we replace the `TypeVar` with the bound). As an additional comment, we do now lose the functionality of the `autodoc_custom_types` -- it should be noted that the `ArrayLike` custom type (the only listed custom type) doesn't appear to be used anywhere in the codebase.
tm91236
added a commit
that referenced
this issue
Mar 31, 2025
By removing the `typehints_formatter` we are able to resolve issues #570 and #734. The former issue is resolved by removing the non-picklable function, which enables build caching, and the second is solved by removing the `TypeVar` bound replacement. While the `TypeVar` replacement does provide more concise documentation, it removes a key piece of information, which the reader must be aware of. For example, in: ```python T = TypeVar("T", bound=Data) def typevar(a: T, b: T) -> None: ... def bound(a: Data, b: Data): ... def valid(a: SupervisedData, b: SupervisedData): ... def invalid(a: Data, b: SupervisedData): ... ``` the `typevar` function is the actual specification, `bound` is the documented specification, `valid` is a valid specification, and `invalid` is an invalid specification which is presented as valid in the documentation (if we replace the `TypeVar` with the bound). As an additional comment, we do now lose the functionality of the `autodoc_custom_types` -- it should be noted that the `ArrayLike` custom type (the only listed custom type) doesn't appear to be used anywhere in the codebase. Refs: #570, #734
9 tasks
tm91236
added a commit
that referenced
this issue
Mar 31, 2025
By removing the `typehints_formatter` we are able to resolve issues #570 and #734. The former issue is resolved by removing the non-picklable function, which enables build caching, and the second is solved by removing the `TypeVar` bound replacement. While the `TypeVar` replacement does provide more concise documentation, it removes a key piece of information, which the reader must be aware of. For example, in: ```python T = TypeVar("T", bound=Data) def typevar(a: T, b: T) -> None: ... def bound(a: Data, b: Data): ... def valid(a: SupervisedData, b: SupervisedData): ... def invalid(a: Data, b: SupervisedData): ... ``` the `typevar` function is the actual specification, `bound` is the documented specification, `valid` is a valid specification, and `invalid` is an invalid specification which is presented as valid in the documentation (if we replace the `TypeVar` with the bound). As an additional comment, we do now lose the functionality of the `autodoc_custom_types` -- it should be noted that the `ArrayLike` custom type (the only listed custom type) doesn't appear to be used anywhere in the codebase. Refs: #570, #734
9 tasks
tm91236
added
wontfix
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
What's the new feature?
Use
autodoc-process-basesto substitute TypeVars for their bounds in base classes in docs. This is similar to the existing function to do it in function annotations.See
documentation/source/conf.pyand https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#event-autodoc-process-bases.What value does this add?
Show inheritance with Intersphinx links without needing to include TypeVars in the compiled documentation. Currently these links are broken.
Is there an alternative you've considered?
No response
Additional context
No response
The text was updated successfully, but these errors were encountered: