sphinx.domains.python.PyXrefMixin.make_xrefs should be consistent with _parse_annotation

[jbms]

Sub-issue split off from #9523.

The tensorstore documentation theme changes sphinx.domains.python.PyXrefMixin.make_xrefs to just use _parse_annotation, so that the formatting of types is the same in both signatures and in the field lists (e.g. "parameters", "return type", "raises" listings):

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

Currently make_xrefs has a separate implementation, perhaps to accommodate more free-form syntax used in older parameter type specifications before the introduction of type annotations, like "int or float":

sphinx/sphinx/domains/python.py

Line 331 in ba2439a

def make_xrefs(self, rolename: str, domain: str, target: str,

I think the older-style "int or float" style should be discourage now that type annotations are so widely used. However, if it is desired to still support them, make_xrefs should still dispatch to _parse_annotations so that real type annotations are displayed consistently.

[tk0miya]

Reasonable. It would be better to support new-style annotations. At the same time, we also support old-styled old-styled type explanations written by narrative. I believe they should be also supported. I believe they're legacy. So it's better to add an option to switch the behavior.

[jbms]

Maybe the old-style syntax and real type annotation syntax can both be supported at the same time, without even needing an option?

Do you know what the old-style syntax can be? Can we assume it is just type annotations separated by or ?

[tk0miya]

Do you know what the old-style syntax can be? Can we assume it is just type annotations separated by or ?

It's described here: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists.
But it does not mean all documents follow this rule because the :type: field takes a free text, not a type.