如何在Sphinx中用intersphinx跨引用Path且省略模块名？

问题场景 #

你有如下Python函数：

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

用Sphinx生成文档时，想通过intersphinx给str和Path都加上跨引用，但Path始终无法生效——原因是Python官方文档的objects.inv里，Path是以pathlib.Path的完整路径索引的。但你不想把文档里的Path改成pathlib.Path或~pathlib.Path，这两种写法在IPython这类交互解释器里显示得很啰嗦。

解决方案 #

方案1：配置autodoc_type_aliases

直接在Sphinx的conf.py里加一段类型映射，告诉Sphinx把文档里的Path对应到pathlib.Path：

autodoc_type_aliases = {
    "Path": "pathlib.Path"
}

这么做之后，Sphinx生成文档时会自动给Path加上正确的跨引用，而Python交互环境里显示的函数签名和文档还是简洁的Path，完全不影响日常使用。

方案2：用sphinx-autodoc-typehints扩展优化

如果你的项目已经在用sphinx-autodoc-typehints处理类型注解，可以直接在conf.py里加这个配置：

autodoc_typehints_format = "short"

这个扩展会自动把导入的类型（比如Path）映射到完整模块路径，同时文档里只显示短名称，既能满足跨引用需求，又不会破坏交互环境的显示效果。

要使用这个扩展得先安装：

pip install sphinx-autodoc-typehints

然后在conf.py的extensions列表里加上'sphinx_autodoc_typehints'。

方案3：兼容旧版Sphinx的类型别名写法

如果你的Sphinx版本比较老，不支持autodoc_type_aliases，可以在模块开头加个同名类型别名：

from pathlib import Path
from typing import Union

# 定义同名别名，不影响代码逻辑，仅用于文档解析
Path = Path

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

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

然后再在conf.py里加上和方案1一样的autodoc_type_aliases配置，就能达到同样的效果。

内容的提问来源于stack exchange，提问作者Mathieu