缩短Sphinx中Python类型注释的显示格式

Question

鉴于名为

mymodule

的模块中的以下函数，我想使用带有

autodoc

的 Sphinx 进行记录：

from typing import Union
from collections.abc import Iterable
from numpy.typing import ArrayLike

def foo(a: Union[str, int], b: Iterable, c: ArrayLike) -> None:
    """Do something useful."""
    pass

在源代码中，函数的签名非常可读。然而，在

autodoc

生成的文档中，签名显示为

khadl._util.foo（a：Union [str，int]，b：collections.abc.Iterable，c：Union [int，float，complex，str，bytes，numpy.generic，Sequence [Union [int，float，复杂，str，字节，numpy.generic]]，序列[序列[Any]]，numpy.typing._array_like._SupportsArray]）→无

这是不可读的。源自

typing

模块的类以简短形式显示（

Union

、

Sequence

、

Any

），但对于抽象基类

Iterable

，会生成唯一标识符 (

collections.abc.Iterable

) 和

 ArrayLike

甚至已“解压”(

Union[int, float, complex, str, bytes, numpy.generic, Sequence[Union[int, float, complex, str, bytes, numpy.generic]], Sequence[Sequence[Any]], numpy.typing._array_like._SupportsArray]

)。

如何配置 Sphinx 以便函数的签名在文档中以可读的方式显示，例如和源代码一样吗？

Answer 1

经过更多挖掘后，我发现可以使用

autodoc_type_aliases

选项来实现此目的。为了让它发挥作用，你必须说

from __future__ import annotations

在您正在记录的模块的开头。 （这会激活注释的延迟评估，如 PEP563 中所述，这将成为 Python 3.10 中的标准。） 然后，您可以告诉 Sphinx 如何打印

conf.py

文件中的注释。

autodoc_type_aliases = {
    'Iterable': 'Iterable',
    'ArrayLike': 'ArrayLike',
}

（每个条目的键是源代码中写入的类型提示，值是生成的文档中的写入方式。）

Answer 2

当我用谷歌搜索这个问题时，我正在寻找autodoc_typehints_format和python_use_unqualified_type_names（

sphinx>=4.0 is required

）：

# put this in your docs/conf.py for Sphinx
autodoc_typehints_format = 'short'
python_use_unqualified_type_names = True

之前

之后