autodoc: Add support for PEP 695's explicit type aliases

[cspotcode]

Is your feature request related to a problem? Please describe.

sphinx cannot document typing.TypeAliasType nor typing_extensions.TypeAliasType.

https://peps.python.org/pep-0695/

Describe the solution you'd like

automodule should document exported TypeAliasTypes without needing a preceding #: comment, the same way that classes and functions do not need a preceding #:.

References to such a type used in the signatures of other functions, types, classes, etc should hyperlink to the type's declaration, the same way that references to a class will hyperlink to the declaration of that class.

The declaration should render similar to how older style type aliases render today, saying "alias of ..."

Describe alternatives you've considered

Additional context

#8934
#11438

[AA-Turner]

PR welcome!

A

[cspotcode]

Should we add a bit of guidance to this issue, for anyone who might attempt it? Like, where would they need to make code changes, or where would they start?

[AA-Turner]

Likely this would be a new Documenter in sphinx/ext/autodoc/__init__.py.

[picnixz]

There's a lot of types that render as alias of ... such as TypeVar and NewType. So I'm wondering whether we could actually unify all those "alias of" under one Documenter instead of having it under the ClassDocumenter.

[Stausssi]

PEP 695 introduces (at least what I've discovered) two problems:

1. As this issue already mentions, type aliases will currently not be documented, even with a leading #: comment. I've already opened up a discussion on python.org to clarify what is the intended docstring format for the new type aliases.
2. Reusing type aliases across files/modules creates an Cannot resolve import of src.module.CustomTypeAliases in src.other_module warning. If warnings-as-errors is set, this will break the build, even tho in Python itself it works fine.

[Stausssi]

Support was added in pyright / pylance via microsoft/pyright#6647 by treating a type alias definition the same as a regular assignment when it comes to docstrings.