我怎样才能生成类似numpy的文档？

Question

我正在使用spyder和对象检查器进行大量工作，我发现这是一个非常方便的即时帮助功能。一些模块似乎从这个功能中获益非常好。例如，一个非常基本的numpy函数（numpy.absolute）在对象检查器中生成以下视图：

我想知道，我如何以这样的方式编写自己的模块，当我在spyder中调用我的函数时会产生这样一个很好的视图。

Answer 1

为了使您的文档能够像numpy一样精美呈现，您需要遵循NumpyDoc标准。假设您有一个名为func的函数，其中包含两个参数：

def func(arg1, arg2):
    return True

要向其添加文档，您需要在其定义下面编写一个多行字符串（在Python world 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旁边写左括号时，也会自动显示。

Answer 2

如果您的Python项目（或文件）已经记录了其他样式（如reStructuredText或Epytext）或未记录，您可以生成/转换文档字符串为NumpyDoc样式使用Pyment：

pyment -o numpydoc /my/python/project

请注意，在安装Pyment之后运行的上一个命令将生成应该应用于代码的补丁。

使用Numpydoc样式记录项目后，您可以使用Sphinx extension生成 nice 可读的NumpyDoc样式文档！