x-ref the python standard library with intersphinx while omitting the module name

EDIT: Other answers than the one I provided are welcome!

Consider the following function:

from pathlib import Path
from typing import Union


def func(path: Union[str, Path]) -> None:
    """My super function.

    Parameters
    ----------
    path : str | Path
        path to a super file.
    """
    pass

When documenting with sphinx, I would like to cross-ref both str and Path with intersphinx. But obviously, it does not work for the latter since it is referenced as pathlib.Path in the objects.inv file.

Is there a way to tell intersphinx/sphinx that Path is from the pathlib module? Without resorting to:

path : str | `pathlib.Path`

or

path : str | `~pathlib.Path`

which does not render nicely in a python interpreter, e.g. IPython.

Answer

numpydoc can do this through x-ref aliases: https://numpydoc.readthedocs.io/en/latest/

In the configuration conf.py:

numpydoc_xref_param_type = True
numpydoc_xref_aliases = {
    "Path": "pathlib.Path",
}

It might try to match other words from the parameters types of the Parameters, Other Parameters, Returns and Yields sections. They can be ignored by adding the following to the configuration conf.py:

numpydoc_xref_ignore = {
    "of",
    "shape",
}

numpydoc also offers other useful tools, such as docsting validation, which can be configured in conf.py with the keys described here: https://numpydoc.readthedocs.io/en/latest/install.html#configuration