Make addition of "alias of..." text optional #12484
Description
Is your feature request related to a problem? Please describe.
When autodoc is used to document a type alias, a line is automatically inserted at the end of the handmade docstring containing the string alias of <TYPE>.
I would like to be able to disable this behavior for a type alias to have full control over the shown documentation text. In particular, if the docstring already contains an explanation of the type, the alias of line is redundant.
Further, this would give me more control on how the alias is presented in the documentation. Currently, other type aliases used are always resolved in the alias of line (see #123456), making the line less understandable in complex situations.
Example of such a situation
For example, if I want to document the type alias of a tuple where the first element is a str, followed by an arbitrary amount of objects of another very complex type alias (for the example: pairs of ints).
from typing_extensions import Unpack, TypeAlias
InnerType: TypeAlias = tuple[int, int]
"""Type alias description of the inner type."""
ComplexType: TypeAlias = tuple[str, Unpack[tuple[InnerType, ...]]]
"""Type alias description of the complex type.
Longer description: Type alias of a tuple starting with a str followed by pairs of ints…
"""If I then use autodoc to document the type aliases:
.. autodata:: ComplexInnerType
.. autodata:: ComplexType
The result is
module-name.InnerType
Type alias description of the inner type.
alias of tuple[int, int]
module-name.ComplexType
Type alias description of the complex type.
Longer description: Type alias of a tuple starting with a str followed by pairs of ints…
alias of tuple[str, Unpack[tuple[tuple[int, int], …]]]
Describe the solution you'd like
I would like to add an option per documented object to disable the addition of the alias of... line.
Say, the option is called no-alias. Then, I could write
.. autodata:: ComplexType
:no-alias:
to disable the addition of the line.
Describe alternatives you've considered
Disabling could also be done by a global option. But this would not give a granular control over the addition of the line.
The removal could also be controlled in conf.py, e.g. by adding an optional set of alias names in conf.py (similar to autodoc_type_aliases) or by adding a hook for the user.
However, I think it's more natural to control this behaviour at the specification of the directive.
Additional context
Possibly related: