我怎样才能生成类似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 项目（或文件）已经用其他样式（asreStructuredText或Epytext）记录或未记录，您可以NumpyDoc使用Pyment将文档字符串生成/转换为样式：

pyment -o numpydoc /my/python/project

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

一旦你的项目使用Numpydoc风格文件，您可以使用狮身人面像的扩展来生成你好看可读NumpyDoc风格的文档！