格式

Python文档字符串可以按照其他文章所示的几种格式编写。但是,没有提到默认的Sphinx docstring格式,它基于 重构文本(reST) . 您可以在 this blog post

请注意,其余部分由 PEP 287

-电子文本

历史上 爪哇文 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
"""

-休息

现在,可能更流行的格式是 重构文本 (reST)使用的格式 Sphinx 注意:它在JetBrains PyCharm中默认使用(在定义方法后键入三个引号并按enter键)。默认情况下,它也用作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
"""

-谷歌

谷歌有自己的 format 这是经常使用的。也可以用狮身人面像来解释 Napoleon plugin

例子:

"""
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.
"""

甚至 more examples

注意,Numpy建议遵循他们自己的 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 将docstring自动生成到尚未记录的Python项目,或将现有docstring(可以混合多种格式)从一种格式转换为另一种格式。

注:示例取自 Pyment documentation

这个 Google style guide 包含一个优秀的Python风格指南。它包括 conventions for readable docstring syntax

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 documentation tutorial . 例如:

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

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

PEP-257 比PEP-8更详细。

然而,docstring似乎比其他代码领域更加个人化。不同的项目会有自己的标准。

我总是倾向于包含docstring,因为它们倾向于演示如何使用函数以及函数的运行速度。

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. 
    ...

显然没有人提到过:你也可以使用 Numpy Docstring标准 . 它在科学界得到了广泛的应用。

• 这个 specification of the format 从纽比和一个 example
• numpydoc
• http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

Napolean sphinx扩展来解析Google风格的docstring(在@Nathan的回答中推荐)也支持Numpy风格的docstring,并使 comparison

最后给出一个基本的例子来说明它的样子:

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

PEP-8 是正式的python编码标准。它包含一个关于docstrings的部分,它引用 PEP-257

是蟒蛇; anything goes . 考虑如何 。除了源代码的读者之外,docstring是不可见的。

人们真的很喜欢在网上浏览和搜索文档。为此,请使用文档工具 Sphinx https://python-guide.readthedocs.org/en/latest/ . 网站 Read the Docs

我建议用弗拉基米尔·凯列舍夫的 pep257 PEP-257 以及 Numpy Docstring Standard 用于描述参数、返回等。