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.

[nyoma-diamond]

+1
Currently type aliases defined in this way are completely ignored which means upgrading to more modern syntax actually introduces a regression in documentation. Previously with TypeAlias or TypeVar you could get Sphinx/autodoc to at least display them as module attributes, but using the new type syntax completely ignores the alias/attribute altogether. I have yet to find a workaround for this.

[AA-Turner]

Are you interested in creating a PR @nyoma-diamond?

[nyoma-diamond]

@AA-Turner While I'd like to, I unfortunately don't have sufficient time or knowledge of Sphinx's codebase to implement this myself. Just thought I'd chip in with some further details from my experience, as I imagine as usage of Python 3.12+ becomes more common this will likely start to become a prevalent issue, particularly given Mypy gained support for PEP 695 in v1.12 last October (and also especially in conjunction with the related issue #8934, which is relevant for Python 3.10+ and was given Mypy support in v0.930).

If my time commitments lighten I might be able to take a peak into this and hack something together, but I don't suspect to get anywhere on that any time soon.