为Sphinx autodoc扩展提供类型提示（PEP 484）支持
项目描述
sphinx-autodoc-typehints
此扩展允许您使用Python 3注解来记录函数可接受的参数类型和返回值类型。请参阅Sphinx渲染的示例，请参阅pyproject-api文档。
这允许您以非常自然的方式使用类型提示，允许您从以下迁移到以下
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，添加未记录参数的存根文档，以便添加类型信息。 -
always_use_bars_union(默认：False)：如果为True，使用PEP 604中描述的 | 运算符显示 Union。例如X|Y或int|None。如果为False，Union 将使用括号中的类型显示。（例如：Union[X, Y]或Optional[int]） -
typehints_document_rtype(默认：True)：如果为False，则永不添加:rtype:指令。如果为True，在未找到现有:rtype:的情况下添加:rtype:指令。 -
typehints_use_rtype(默认：True)：控制当typehints_document_rtype设置为True时的行为。如果为True，在:rtype:指令中记录返回类型。如果为False，将返回类型记录为:return:指令的一部分，如果存在，否则回退到使用: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]。如果为False，保留 "Optional"-类型。注意：如果为False，任何 包含None的 Union 都将显示为 Optional！注意：如果一个可选参数只有一个类型（例如 Optional[A] 或 Union[A, None]），它将 始终 显示为 Optional！ -
typehints_formatter(默认：None)：如果设置为函数，则此函数将用annotation作为第一个参数和sphinx.config.Config参数作为第二个参数调用。该函数应返回一个包含 reStructuredText 代码的字符串或None以回退到默认格式化程序。 -
typehints_use_signature(默认：False)：如果为True，则在签名中显示类型提示。 -
typehints_use_signature_return(默认：False)：如果为True，则在签名中显示返回注释。
工作原理
扩展监听 Sphinx 的 autodoc-process-signature 和 autodoc-process-docstring 事件。在前者中，它从函数签名中删除注释。在后者中，它将适当的 :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 并移除引号。
下载文件
下载适合您平台的电影。如果您不确定要选择哪个，请了解更多关于 安装包 的信息。
源分发
构建分发
散列值 for sphinx_autodoc_typehints-2.4.4-py3-none-any.whl
| 算法 | 散列摘要 | |
|---|---|---|
| SHA256 | 940de2951fd584d147e46772579fdc904f945c5f1ee1a78c614646abfbbef18b |
|
| MD5 | 71e71a16bf7b9739ee0dba332ca95dd4 |
|
| BLAKE2b-256 | 6e8b1f0474e576ea6c035ddf7b064474f7d3598edc8404a088ec1194d8386db6 |