python - 如何生成类似 numpy 的文档？

Question

我经常使用 spyder 和对象检查器，我发现它作为即时帮助功能非常方便。一些模块似乎从这个功能中获益良多。例如，一个非常基本的 numpy 函数 (numpy.absolute) 在对象检查器中生成以下 View :

我想知道如何编写自己的模块，以便在调用 spyder 中的函数时产生如此漂亮的 View 。

Answer 1

为了使您的文档呈现得像 numpy 一样好，您需要遵循 NumpyDoc标准。假设您有一个名为 func 的函数，带有两个参数，如下所示:

def func(arg1, arg2):
    return True

要向其添加文档，您需要在其定义下方编写一个多行字符串(在 Python 世界中称为 docstring)，如下所示

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    Examples
    --------
    >>> func(1, "a")
    True
    """
    return True

Spyder 所做的是获取纯文本描述，将其解析并呈现为 html，最后在 Object Inspector 中显示。

要查看它，您只需在代码中的其他地方调用 func 并在其旁边按 Ctrl+i，如下所示:

func<Ctrl+i>(1, "a")

当您在 func 旁边写一个左括号时，这也会自动显示。