如何解决跳过文档中的类型提示
让我们考虑以下功能:
def f(x: int,y: int) -> int:
"""Get sum of two integers.
Parameters
----------
x : int
first integer
y : int
second integer
Returns
-------
int
sum of the provided integers
"""
return x + y
使用Sphinx(v3.2.1)进行文档编制时,该文档以以下形式生成:
但是,在函数文档的标题以及f(x: int,y:int) -> int
部分中,我看不到要在Parameters
中显示类型提示的要点。在这种情况下,这并不重要,但是对于带有4-5个参数的函数来说,它变得非常难以理解。有没有办法跳过类型提示?就像,我希望标题是f
或f(x,y)
。
我希望这与add_function_parentheses
有关,但是在False
中将其设置为conf.py
并没有引起我的注意。
一个相关的问题是,如果类型提示很长,可能像typing.Union
,但有多个长描述,而我不想使用typing.Any
,我经常将它们写在文档字符串中,跨多行,并遵守最大行数限制。在这些情况下,Parameters
部分将显示类型是第一行中的内容,而下一行仅是描述。我不确定这个问题是否相同,因此我不附加此示例。如果是这样,请告诉我,我将举一个示例进行更新。
解决方法
autodoc-process-signature
事件的处理程序可以更改签名并返回函数和方法的注释。
下面是一个简单的示例。如果将此代码添加到conf.py,则会从输出中删除所有签名和返回注释。
def fix_sig(app,what,name,obj,options,signature,return_annotation):
return ("","")
def setup(app):
app.connect("autodoc-process-signature",fix_sig)
,
sphinx.ext.autodoc
有一个选项autodoc_typehints
。它具有3个选项:none
,description
和signature
(默认)。使用none
或description
中的任何一个都会在标题行中隐藏类型提示。我可以发现这两者之间的唯一区别是,如果文档字符串不包含类型建议,description
仍将在从类型提示收集的文档中显示它们。
要使用此功能,请在conf.py
中进行以下更改:
- 在
sphinx.ext.autodoc
中添加extensions
(如果尚未添加) - 设置
autodoc_typehints = "none"
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 dio@foxmail.com 举报,一经查实,本站将立刻删除。