给定一个名为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
模块的类以简短形式显示(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,使函数的签名以可读的方式显示在文档中,例如,在源代码中?
2条答案
按热度按时间nuypyhwy1#
经过进一步的挖掘,我发现
autodoc_type_aliases
选项可以用来实现这一点。(这将激活PEP563中概述的注解的延迟求值,它将成为Python 3.10中的标准)。然后,您可以告诉Sphinx如何打印
conf.py
文件中的注解。(The每个条目的key是在源代码中编写的类型提示,value是它在生成的文档中的编写方式。)
yjghlzjz2#
当我在谷歌上搜索这个问题时,我正在寻找autodoc类型提示格式和python类型名称(
sphinx>=4.0 is required
):之前
之后