sphinx.domains.python._type_to_xref should support configurable aliases/overrides

[jbms]

This is a sub-issue split off from #9523.

In some cases it is useful for a type annotation to specify something that isn't a real Python type, such as array_like. In that case, we would like references to that "type" to cross-link to some other type of reference target, rather than a py:obj target.

Sphinx should support a configuration option for specifying a mapping from "type name" to (refdomain, reftype, reftarget), and also allow configuring additional hooks for modifying type references. For example, users may wish to strip off the module prefix for certain types.

Currently there is just a hard coded list of substitutions in the tensorstore documentation, but this should be refactored to use a config options:

https://github.com/google/tensorstore/blob/1a59fcb310bc1feb13569f03f7134b4c3a5fa5f4/docs/tensorstore_sphinx_ext/autodoc.py#L201

[tk0miya]

I feel your idea is very similar to the napoleon_type_aliases. Does it help you? https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_type_aliases

[jbms]

That is true, it is very similar to that option. The difference is that I would like the aliases to apply uniformly to all type annotations that are displayed (i.e. in signatures as well), not just in parameter lists, and not just when using napoleon.

Perhaps we could add python_type_aliases that behaves like napoleon_type_aliases but applies to all type annotations? There is also the question of what syntax to use --- I guess ideally there should be a way to specify arbitrary rst code to be inserted, but perhaps also a way to specify an alternative type annotation as a string, which should then be re-parsed and re-processed by _parse_annotation.