摘要：问题描述：我见过几种用 Python 编写文档字符串的不同风格，其中最流行的风格是什么？解决方案 1：格式正如其他文章所示，Python 文档字符串可以按照多种格式编写。但是，未提及默认的 Sphinx 文档字符串格式，该格式基于reStructuredText (reST) 。您可以在此博客文章中获取有关主...

问题描述：

我见过几种用 Python 编写文档字符串的不同风格，其中最流行的风格是什么？

解决方案 1：

格式

正如其他文章所示，Python 文档字符串可以按照多种格式编写。但是，未提及默认的 Sphinx 文档字符串格式，该格式基于reStructuredText (reST) 。您可以在此博客文章中获取有关主要格式的一些信息。

请注意，reST 是PEP 287推荐的

以下是文档字符串的主要使用格式。

Epytext

历史上，类似javadoc的风格很流行，因此它被用作Epydoc（具有调用Epytext格式）生成文档的基础。

例子：

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

休息

如今，可能更流行的格式是Sphinx用于生成文档的reStructuredText (reST) 格式。注意：JetBrains PyCharm 默认使用该格式（定义方法后输入三引号并按回车键）。Pyment 也默认使用该格式作为输出格式。

例子：

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

谷歌

Google 有自己的常用格式。它也可以被 Sphinx 解释（即使用Napoleon 插件）。

例子：

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

更多示例

-Numpydoc

请注意，Numpy 建议遵循基于 Google 格式并可供 Sphinx 使用的numpydoc 。

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

转换/生成

可以使用Pyment这样的工具自动为尚未记录的 Python 项目生成文档字符串，或者将现有的文档字符串（可以混合多种格式）从一种格式转换为另一种格式。

注意：示例取自Pyment 文档

解决方案 2：

Google 风格指南包含一份出色的 Python 风格指南。它包含可读文档字符串语法的约定，提供比 PEP-257 更好的指导。例如：

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

我喜欢扩展它，在参数中包含类型信息，如Sphinx 文档教程中所述。例如：

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

解决方案 3：

PEP-257中的文档字符串约定比 PEP-8 更详细。

然而，文档字符串似乎比代码的其他部分更加个性化。不同的项目会有自己的标准。

我倾向于始终包含文档字符串，因为它们倾向于快速演示如何使用该函数以及它的作用。

无论字符串的长度如何，我都希望保持一致。我喜欢在缩进和间距一致的情况下编写代码。这意味着，我使用：

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

超过：

def sq(n):
    """Returns the square of n."""
    return n * n

并且倾向于在较长的文档字符串中省略第一行的注释：

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

这意味着我发现像这样开头的文档字符串很混乱。

def sq(n):
    """Return the squared result. 
    ...

解决方案 4：

显然没有人提到它：您也可以使用Numpy Docstring 标准。它在科学界被广泛使用。

来自 numpy的格式规范以及示例
你有一个 sphinx 扩展来呈现它：numpydoc
以下是呈现的文档字符串多么美观的示例：http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

用于解析 Google 风格文档字符串的 Napolean sphinx 扩展（在@Nathan 的回答中推荐）也支持 Numpy 风格的文档字符串，并对两者进行了简短的比较。

最后给出一个基本的例子来说明它是什么样子的：

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

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True