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

zmeyuzjn  于 2023-01-08  发布在  Python
关注(0)|答案(2)|浏览(130)

给定一个名为mymodule的模块中的以下函数,我希望使用Sphinx和autodoc来记录该函数:

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生成的文档中,签名显示为
kadl._util.foo(a:并集[字符串,整数],B:集合。abc。可迭代,c:并集[整数,浮点数,复数,字符串,字节,数字.泛型,序列[并集[整数,浮点数,复数,字符串,字节,数字.泛型]],序列[序列[任何]],数字.类型._类似数组._SupportsArray])→无
源于typing模块的类以简短形式显示(UnionSequenceAny),但是对于抽象基类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,使函数的签名以可读的方式显示在文档中,例如,在源代码中?

nuypyhwy

nuypyhwy1#

经过进一步的挖掘,我发现autodoc_type_aliases选项可以用来实现这一点。

from __future__ import annotations

(这将激活PEP563中概述的注解的延迟求值,它将成为Python 3.10中的标准)。然后,您可以告诉Sphinx如何打印conf.py文件中的注解。

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

(The每个条目的key是在源代码中编写的类型提示,value是它在生成的文档中的编写方式。)

yjghlzjz

yjghlzjz2#

当我在谷歌上搜索这个问题时,我正在寻找autodoc类型提示格式和python类型名称(sphinx>=4.0 is required):

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

之前

之后

相关问题