Option to prevent expanding types in signatures

[orenbenkiki]

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

Say I have a function foo(bar: MyType) -> None: ... where MyType = Union[...], which is exported from some other module, with nice associated documentation desctribing what this type means, what each alternative means, etc.

What I would like to see in the type signature of the generated documentation is just the single word MyType linking to the type's definition and helpful documentation.

What I actually get is the expanded Union, which is next to impossible to read, and doesn't link to the detailed documentation I have for MyType.

Describe the solution you'd like

Some option autodoc_expand_types = False which would tell autodoc to not replace named types it has documentation for, but instead just keep their nice short name and directly link to their documentation instead.

Describe alternatives you've considered

Setting autodoc_type_aliases = { "MyType": "my.module.MyType" } has no effect (maybe because MyType is imported from a different module?)

Setting autodoc_typehints_format = "short" is nice, but doesn't apply here. It is also logically an unrelated option (it would be nice nice if there was a "short_only_for_my_package" option, or "short_only_for_a_list_of_packages", but that's a whole different issue).

Additional context

It is entrirely possible that there's some existing option somewhere that has this effect, but I couldn't find any. In general it is easy to find what a specific sphinx option does, but there seems to be no categorized cental list of all available options (I'm talking about all options available in the standard distribution, of course; e.g., sphinx.ext.autodoc is part of the sphinx package itself).

[rogerbinns]

Some more things that don't work. sphinx-build 7.3.7

My code has this where everything is in the same module:

QUERY = COLUMNFILTER | NEAR | AND | OR | NOT | PHRASES
"docstring explaining this"

I have functions like:

def some_method(a: QUERY, b: QUERY) -> QUERY:

In default configuration the Sphinx output is unreadable because it expands QUERY in all 3 occurrences.

some_method(a: COLUMNFILTER | NEAR | AND | OR | NOT | PHRASES, b: COLUMNFILTER | NEAR | AND | OR | NOT | PHRASES)→ COLUMNFILTER | NEAR | AND | OR | NOT | PHRASES:

Some things that do not work:

autodoc_type_aliases

This has no effect:

autodoc_type_aliases = {"my.module.QUERY": "my.module.QUERY"}

TypeAlias

QUERY: TypeAlias = COLUMNFILTER | NEAR | AND | OR | NOT | PHRASES

This expands QUERY.

Python 3.12 keyword

Python 3.12 lets you use type:

type QUERY = COLUMNFILTER | NEAR | AND | OR | NOT | PHRASES

This results in QUERY not being expanded which is good, but it is not clickable and there is no role that can reference it.