如何生成类似numpy的文档？

Question

我在使用spyder这个工具，特别是它的对象检查器功能，这个功能让我觉得非常方便，就像是一个即时帮助的助手。有些模块在这个功能下表现得特别好。例如，numpy这个库里的一个很基础的函数（numpy.absolute）在对象检查器中显示的效果如下：

我想知道，怎样才能写出自己的模块，让我的函数在spyder中调用时也能显示出这么好的效果。

Answer 1

如果你的Python项目（或者文件）已经用其他风格（比如reStructuredText或者Epytext）进行了文档说明，或者根本没有文档，你可以使用Pyment把文档字符串转换成NumpyDoc风格：

pyment -o numpydoc /my/python/project

请注意，前面的命令是在安装了Pyment之后运行的，它会生成一些补丁，这些补丁需要应用到你的代码上。

一旦你的项目用Numpydoc风格进行了文档说明，你就可以使用Sphinx扩展来生成你那种好看且易读的NumpyDoc风格文档！

Answer 2

为了让你的文档看起来和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格式，最后在对象检查器中显示出来。

要查看这个文档，你只需要在代码的其他地方调用func，然后在旁边按下Ctrl+i，像这样：

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

当你在func旁边写左括号时，这个文档也会自动显示出来。