跳过文档中的类型提示

编程问答 2022-08-15

问题描述

让我们考虑以下功能：

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）进行文档编制时，该文档以以下形式生成：

enter image description here

但是，在函数文档的标题以及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中进行以下更改：

  1. 在sphinx.ext.autodoc中添加extensions（如果尚未添加）
  2. 设置autodoc_typehints = "none"
autodocpythonpython-sphinxsphinx-napoleontype-hinting