跳过文档中的类型提示

Question

让我们考虑以下函数：

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 有关，但在 conf.py 中将其设置为 False 并没有我注意到的任何效果。

一个相关的问题是，如果类型提示很长，可能像 typing.Union 有多个长描述，我不想在其中使用 typing.Any，我经常将它们写在文档字符串中多行，遵守最大行数限制。在这些情况下，Parameters 部分显示类型是第一行中的内容，下一行只是描述。我没有附上这个问题的例子，因为我不确定它们是否相同。如果是，请告诉我，我会用示例进行更新。

Answer 1

autodoc-process-signature 事件的处理程序可以更改函数和方法的签名和 return 注释。

下面是一个简单的例子。如果将此代码添加到 conf.py，所有签名和 return 注释将从输出中删除。

def fix_sig(app, what, name, obj, options, signature, return_annotation):
    return ("", "")
 
def setup(app):
    app.connect("autodoc-process-signature", fix_sig)

Answer 2

sphinx.ext.autodoc 有一个选项 autodoc_typehints。这有 3 个选项：none、description 和 signature（默认）。使用 none 或 description 中的任何一个都将隐藏 header 行中的类型提示。我能在这两者之间找到的唯一区别是，如果文档字符串不包含类型建议，description 仍会在从类型提示收集的文档中显示它们。

要使用它，需要在 conf.py 中进行以下更改：

在 extensions 中添加 sphinx.ext.autodoc（如果尚未完成）
设置autodoc_typehints = "none"

跳过文档中的类型提示

Skipping type hints in documentation

python

type-hinting

python-sphinx

autodoc

sphinx-napoleon