要使用autodoc-typehints记录没有函数签名的可调用对象,可以按照以下步骤进行操作:
安装Sphinx和sphinx-autodoc-typehints:
pip install Sphinx sphinx-autodoc-typehints
在Sphinx项目的conf.py
文件中添加以下配置:
# conf.py
extensions = [
...
'sphinx.ext.autodoc',
'sphinx_autodoc_typehints',
...
]
# 设置autodoc-typehints的类型推断级别,默认为1(仅基于注释),可以设置为2(基于函数签名)
autodoc_typehints = 'description'
# 设置是否在文档中显示类型提示,默认为False
autodoc_typehints_description_target = 'documented'
在需要记录可调用对象的模块中使用类型提示语法,例如函数参数的类型提示和返回值的类型提示:
def add(a: int, b: int) -> int:
"""Adds two numbers."""
return a + b
运行Sphinx生成文档:
sphinx-build -b html
这将生成HTML格式的文档。
如果你已经有一个Sphinx项目并且只想更新文档,可以使用以下命令:
make html
这将使用Makefile中的配置来生成文档。
在生成的文档中,你将看到可调用对象的函数签名以及类型提示信息。
这是一个完整的示例:
# mymodule.py
def add(a: int, b: int) -> int:
"""Adds two numbers."""
return a + b
# conf.py
extensions = [
...
'sphinx.ext.autodoc',
'sphinx_autodoc_typehints',
...
]
autodoc_typehints = 'description'
autodoc_typehints_description_target = 'documented'
最后,运行Sphinx命令生成文档:
sphinx-build -b html . _build
在生成的HTML文档中,你将看到add
函数的函数签名和类型提示信息。