Numpy sphinxcontrib.napoleon和numpy.numpydoc的区别

在本文中，我们将介绍NumPy中的两种文档生成工具——sphinxcontrib.napoleon和numpy.numpydoc。这两种工具都是用于生成NumPy函数和类的文档，但是它们之间仍然存在一些区别。

阅读更多：Numpy 教程

sphinxcontrib.napoleon

sphinxcontrib.napoleon是Sphinx的一个插件，它提供了一种更简洁的方式来写函数和类的docstrings。相较于标准的Numpydoc格式，napoleon风格更加简洁、易读，并且更为友好。

sphinxcontrib.napoleon官方文档提供了一个简单的例子。下面是numpydoc格式的文档：

def foo(bar, vik=None):
    """[summary]

    Long-form

    Parameters
    ----------
    bar : array_like

    vik : int, optional

    Returns
    -------
    type
        Explanation of return value

    See Also
    --------
    similar_function : Does something similar, but different.
    """
    pass

相同的函数，使用使用napoleon风格的文档将变为：

def foo(bar, vik=None):
    """[summary]

    Parameters
    ----------
    bar : array_like
        Explanation of `bar`
    vik : int, optional
        Explanation of `vik`

    Returns
    -------
    type
        Explanation of return value

    See Also
    --------
    similar_function : Does something similar, but different.
    """
    pass

可以看到，两种格式具有相同的信息，但是sphinxcontrib.napoleon格式更为简洁。bar和vik的解释已经位于其参数类型的后面，不需要再写出参数类型。此外，在参数列表中要求指定每个参数的类型和描述可能使得numpydoc格式的文档变得更加冗长。

numpy.numpydoc

numpy.numpydoc是NumPy提供的标准文档格式。与sphinxcontrib.napoleon不同，numpydoc格式更为详细，这当然也意味着numpydoc格式的文档更加冗长。

下面是一段使用numpy.numpydoc编写的docstring的例子：

def foo(bar, vik=None):
    """[summary]

    This is a long-form explanation of what this function does and how it is useful.
    It may include multiple paragraphs and should end with a :Examples: block if there are examples provided.

    Parameters
    ----------
    bar : ndarray
        Explanation of what `bar` is and what it means.
    vik : int or None, optional
        Explanation of what `vik` is and what it means.
        Default is `None`.

    Returns
    -------
    ndarray
        Explanation of the return value.

    Examples
    --------
    First example of how to use this function.

    >>> x = foo(bar, vik=3)

    Second example of how to use this function.

    >>> x = foo(bar)
    """
    pass

可以看到，numpydoc格式的docstring中包含了更多细节，例如函数的长形式说明以及参数类型和默认值。虽然这样写程序员更能理解函数是如何工作的，但如果我们换了一个稍微复杂点的函数，这样写就会变得非常冗长，不利于阅读。

特性比较

综上所述，两种格式都有优点和缺点，需要开发人员进行权衡并选择适合他们的文档格式。

对于一些简单的函数，我们可以使用sphinxcontrib.napoleon来提高开发效率和可读性。但如果函数存在复杂性或需要详细的说明，那么numpy.numpydoc会是更好的选择。

下表展示了两种格式的比较：

功能	sphinxcontrib.napoleon	numpy.numpydoc
简洁易读	是	否
内容详细	否	是
对程序员而言更简单进行文档编写	是	否

总结

在NumPy中，sphinxcontrib.napoleon和numpy.numpydoc都是很好的文档生成工具。sphinxcontrib.napoleon提供更加简洁易读的文档格式，适用于文档较少或简单的函数和类。而numpy.numpydoc则提供更加详细的文档格式，适用于复杂的函数和类。根据不同的情况，开发人员可以自由选择适合的文档生成工具来提高开发效率和可读性。