对 Sphinx autodoc 扩展的类型提示 (PEP 484) 支持
项目描述
sphinx-autodoc-typehints
此扩展允许您使用 Python 3 注释来记录可接受的参数类型和函数的返回值类型。这允许您以非常自然的方式使用类型提示，允许您从中迁移：
def format_unit(value, unit):
"""
Formats the given value as a human readable string using the given units.
:param float|int value: a numeric value
:param str unit: the unit for the value (kg, m, etc.)
:rtype: str
"""
return f"{value} {unit}"
对此：
from typing import Union
def format_unit(value: Union[float, int], unit: str) -> str:
"""
Formats the given value as a human readable string using the given units.
:param value: a numeric value
:param unit: the unit for the value (kg, m, etc.)
"""
return f"{value} {unit}"
安装和设置
首先，使用 pip 下载并安装扩展：
$ pip install sphinx-autodoc-typehints
然后，将扩展名添加到您的conf.py：
extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints"]
选项
接受以下配置选项：
-
typehints_fully_qualified（默认值：）False：如果True，类名总是完全限定的（例如module.for.Class）。如果False，只显示类名（例如Class） -
always_document_param_types（默认值：）False：如果False是，则不要为未记录的参数添加类型信息。如果True是，为未记录的参数添加存根文档，以便能够添加类型信息。 -
typehints_document_rtype（默认值：True）：如果False，从不添加:rtype:指令。如果，如果没有找到现有True的指令，则添加 指令。:rtype::rtype: -
typehints_use_rtype（默认值True：）：控制typehints_document_rtype设置为 时的行为True。如果 ，则在指令True中记录返回类型。:rtype:IfFalse，文档返回类型作为:return:指令的一部分，如果存在，否则回退到 using:rtype:。与 napoleon_use_rtype结合使用 以避免生成重复或冗余的返回类型信息。 -
typehints_defaults（默认值：）None：如果None是，则不添加默认值。否则，添加默认注释：'comma'在类型之后添加它，将 Sphinx 的默认外观更改为“ param ( int , default:1) -- text”。'braces'在类型之后添加(default: ...)（对于类似 numpydoc 的样式很有用）。'braces-after'(default: ...)而是在参数文档文本的末尾添加。
-
simplify_optional_unions（默认值：）True：如果True是，则“Union[...]”类型的可选参数在生成的文档中被简化为 Union[..., None] 类型（例如 Optional[Union[A, B]] ->联合[A，B，无]）。如果False，则保留“可选”类型。注意：如果False，任何包含的 UnionNone都将显示为 Optional！注意：如果可选参数只有一种类型（例如 Optional[A] 或 Union[A, None]），它将始终显示为 Optional！ -
typehints_formatter（默认值：）None：如果设置为函数，该函数将annotation作为第一个参数和sphinx.config.Config第二个参数调用。该函数应返回带有 reStructuredText 代码的字符串或None回退到默认格式化程序。
这个怎么运作
扩展监听autodoc-process-signature和autodoc-process-docstringSphinx 事件。在前者中，它从函数签名中剥离注释。在后者中，它将适当的:type argname:和
:rtype:指令注入到文档字符串中。
只有在文档字符串中具有现有:param:指令的参数才会添加它们各自的:type:指令。:rtype:当且仅当没有找到现有指令时才添加该指令:rtype:。
与 sphinx.ext.napoleon 的兼容性
要将sphinx.ext.napoleon与 sphinx-autodoc-typehints 一起使用，请确保先加载sphinx.ext.napoleon，然后再加载 sphinx-autodoc-typehints。有关更多信息，请参阅问题跟踪器上的问题15 。
处理循环进口
有时来自两个不同模块的函数或类需要在它们的类型注释中相互引用。这会产生循环导入问题。解决方案如下：
- 仅导入模块，而不是其中的类/函数
- 在类型注释中使用前向引用（例如
def methodname(self, param1: 'othermodule.OtherClass'):）
在 Python 3.7 上，您甚至可以使用from __future__ import annotations和删除引号。
使用类型提示注释
如果您正在记录需要与 Python 2.7 保持兼容的代码，则不能使用常规类型注释。相反，您必须使用 Python 3.8 或更高版本，或者安装了typed_ast
。包 extrastype_comments将自动引入适当的依赖项。然后您可以通过以下方式添加类型提示注释：
def myfunction(arg1, arg2):
# type: (int, str) -> int
return 42
或者：
def myfunction(
arg1, # type: int
arg2, # type: str
):
# type: (...) -> int
return 42
