格式

Question

我在Python中看过几种不同风格的文档字符串，是否有官方或“同意”的风格？

Answer 1

格式

Python文档字符串可以按照其他帖子显示的几种格式编写。但是，未提及默认的Sphinx文档字符串格式，并且基于 reStructuredText（reST）。您可以在that tuto中获取有关主要格式的一些信息。

请注意，PEP 287

建议使用reST

以下是docstrings的主要使用格式。

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

- reST

如今，可能更为流行的格式是Sphinx用于生成文档的 reStructuredText （reST）格式。注意：默认情况下，它在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
"""

- Google

Google经常使用自己的format。它也可以由Sphinx解释（即使用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

- Numpydoc

请注意，Numpy建议您根据Google格式关注自己的numpydoc并使用Sphinx。

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

Answer 2

Docstring约定在PEP-257中，比PEP-8更详细。

然而，docstrings似乎比其他代码领域更加个性化。不同的项目将有自己的标准。

我倾向于总是包含文档字符串，因为它们倾向于演示如何使用函数及其快速完成的功能。

无论字符串的长度如何，我都希望保持一致。我喜欢当缩进和间距一致时如何编码外观。这意味着，我使用：

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

Answer 3

很明显没有人提到它：你也可以使用 Numpy Docstring Standard 。它被广泛用于科学界。

来自numpy的specification of the format和example
您有一个sphinx扩展程序来呈现它：numpydoc
以及渲染文档字符串的漂亮程度示例：http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

用于解析Google风格文档字符串的Napolean sphinx扩展（在@Nathan的答案中推荐）也支持Numpy风格的文档字符串，并使两者都缩短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

Answer 4

PEP-8是官方的python编码标准。它包含一个关于文档字符串的部分，它引用了PEP-257 - 文档字符串的完整规范。

Answer 5

我建议使用Vladimir Keleshev的pep257 Python程序检查您的文档字符串对PEP-257和Numpy Docstring Standard的描述参数，返回等。

pep257将报告您从标准中产生的分歧，并被称为pylint和pep8。

Answer 6

这是Python; anything goes。考虑如何发布您的文档。除了源代码的读者之外，文档字符串是不可见的。

人们非常喜欢浏览和搜索网络上的文档。为此，请使用文档工具Sphinx。它是记录Python项目的事实上的标准。产品很漂亮 - 看看https://python-guide.readthedocs.org/en/latest/。网站Read the Docs将免费托管您的文档。

什么是标准的Python文档字符串格式？

6 个答案:

格式

- Epytext

- reST

- Google

- Numpydoc

变换/生成