如何生成类似 numpy 的文档？答案

【问题标题】：How can I produce a numpy-like documentation?如何生成类似 numpy 的文档？
【发布时间】：2014-08-24 16:09:36
【问题描述】：

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

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

【问题讨论】：

标签： python numpy documentation spyder docstring

【解决方案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 旁边写一个左括号时，它也会自动显示。

【讨论】：

numpydoc 绝对令人惊叹，更多项目应该采用的东西
绝对！几乎所有 Python 科学项目都使用它，但我认为 Spyder 的 Object Inspector 鼓励更广泛的受众在他/她的代码中采用它。
您可以通过单击函数定义（无需在其他地方调用）并按 CTRL+Q（在 Windows 上）来查看快速文档（在 PyCharm 中）。它可能在其他 IDE 或 OS 中类似地工作。干杯！

【解决方案2】：

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

pyment -o numpydoc /my/python/project

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

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

【讨论】：

这个答案以前怎么没有被发现和赞成？这是我一直在寻找的，很长一段时间。谢谢！