如何在 sphinx 文档中自动添加参数类型
How to automatically add parameter types in sphinx documentation
我目前正在尝试使用 Sphinx 实现自动文档创建(使用扩展 sphinx-apidoc 和 napoleon)。这工作得很好,但如果类型提示(PEP484 约定)自动添加到参数列表中会更好。
我想知道这是否可能。
更具体地说:(来自napoleon example)
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
"""Example function with PEP 484 type annotations.
Args:
param1: The first parameter.
param2: The second parameter.
Returns:
The return value. True for success, False otherwise.
"""
渲染如下:
参数列表有所有参数,但没有附上类型。可以手动添加它们,但这可能会在决定更改签名时引入未来问题。
手动添加类型的示例:
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
"""Example function with PEP 484 type annotations.
Args:
param1 (int): The first parameter.
param2 (str): The second parameter.
Returns:
The return value. True for success, False otherwise.
"""
呈现为:
您现在可以使用 sphinx-autodoc-typehints 扩展程序。当您在上面的前一个示例中编写时,它会自动将类型添加到 sphinx 文档字符串中。
要安装,只需执行以下操作:
$ pip install sphinx-autodoc-typehints
将 'sphinx_autodoc_typehints'
添加到 conf.py
'sphinx.ext.napoleon'
中的 extensions
列表中,并确保您还添加了 napoleon_use_param = True
到 conf.py
.
我目前正在尝试使用 Sphinx 实现自动文档创建(使用扩展 sphinx-apidoc 和 napoleon)。这工作得很好,但如果类型提示(PEP484 约定)自动添加到参数列表中会更好。
我想知道这是否可能。
更具体地说:(来自napoleon example)
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
"""Example function with PEP 484 type annotations.
Args:
param1: The first parameter.
param2: The second parameter.
Returns:
The return value. True for success, False otherwise.
"""
渲染如下:
参数列表有所有参数,但没有附上类型。可以手动添加它们,但这可能会在决定更改签名时引入未来问题。
手动添加类型的示例:
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
"""Example function with PEP 484 type annotations.
Args:
param1 (int): The first parameter.
param2 (str): The second parameter.
Returns:
The return value. True for success, False otherwise.
"""
呈现为:
您现在可以使用 sphinx-autodoc-typehints 扩展程序。当您在上面的前一个示例中编写时,它会自动将类型添加到 sphinx 文档字符串中。
要安装,只需执行以下操作:
$ pip install sphinx-autodoc-typehints
将 'sphinx_autodoc_typehints'
添加到 conf.py
'sphinx.ext.napoleon'
中的 extensions
列表中,并确保您还添加了 napoleon_use_param = True
到 conf.py
.