tuple with generic parameter not correctly documented with autodoc_typehints = 'description' (result of signature is ok)

Describe the bug

autodoc_typehints = 'description' fails to correctly document cases like tuple[T] and tuple [T, T], while it correctly documents cases like typing.Tuple[T] and typing.,Tuple[T, T] and cases like tuple[int] and tuple[int, int].

autodoc_typehints = 'signature' correctly documents all of these cases.

Example code:

from typing import TypeVar, Generic, Tuple

T = TypeVar("T")

class MyClass(Generic[T]):

    def test1(self, a: tuple[int], b: Tuple[int]) -> None:
        return

    def test2(self, a: tuple[int, int], b: Tuple[int, int]) -> None:
        return

    def test3(self, a: tuple[T], b: Tuple[T]) -> None:
        return

    def test4(self, a: tuple[T, T], b: Tuple[T, T]) -> None:
        return

Correctly documented with autodoc_typehints = 'signature' as:

class nographs_playground.MyClass
    test1(a: tuple[int], b: Tuple[int]) → None
    test2(a: tuple[int, int], b: Tuple[int, int]) → None
    test3(a: tuple[T], b: Tuple[T]) → None
    test4(a: tuple[T, T], b: Tuple[T, T]) → None

But autodoc_typehints = 'description' fails to correctly document the tuple[t] and tuple [T, T] in test3 and test4: "~T" instead of "T" is given into the HTML code.

In all other cases, 'description' correctly interprets and documents like 'signature' does.

class nographs_playground.MyClass
    test1(a, b)
        Parameters
                a (tuple[int]) -
                b (Tuple[int]) -
        Return type
            None

    test2(a, b)
        Parameters
                a (tuple[int, int]) -
                b (Tuple[int, int]) -
        Return type
            None

    test3(a, b)
        Parameters
                a (tuple[~T]) -
                b (Tuple[T]) -
        Return type
            None

    test4(a, b)
        Parameters
                a (tuple[~T, ~T]) -
                b (Tuple[T, T]) -
        Return type
            None

Here is the ZIP of the project, with source and docs configuration. In line 64+65 of file nographs_playground\docs\source\conf.py, the value of autodoc_typehints can by switched between the to options.

nographs_playground.zip

How to Reproduce

docs/make.bat html

Expected behavior

For option autodoc_typehints = 'description':

• tuple[T] should be described in generated HTML as tuple[T], and not as tuple[~T].

• tuple[T, T] should be described as tuple[T, T] and not as tuple[~T, ~T].

So, the output should be the same as for autodoc_typehints = 'signature', and it should be consistent with the output for typing.Tuple[T] and typing.Tuple[T] and with the output for tuple[int] and for tuple[int, int].

Your project

See ZIP in description

Screenshots

Wrong output is shown in description

OS

Win

Python version

3.10

Sphinx version

5.2.1

Sphinx extensions

sphinx.ext.autodoc and sphinx-rtd-theme

Extra tools

No response

Additional context

Sphinx and sphinx.ext.autodoc are extremely helpful tools. Thank you very much for you work!

For short signatures, I prefer autodoc_typehints = 'signature', but for long signatures, autodoc_typehints = 'description' is much better. Thank you for this option.

Start with the autodoc_typehints setting around lines 64–65 of nographs_playground\docs\source\conf.py, then run docs/make.bat html to compare the description and signature outputs. Trace how generic tuple annotations are rendered in the generated HTML; done means tuple[T] and tuple[T, T] display T rather than ~T in description mode.