标准Python Docstring格式是什么？ [关闭
https://stackoverflow.com/questions/3898572
-
29-09-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russian题
我在Python看到了一些不同的撰写Docstring的样式，是否有官方或“商定”风格？
解决方案
格式
如其他帖子所示，可以按照几种格式编写Python Docstrings。但是，尚未提及默认的狮身人面像docstring格式，并且基于 重组文本（休息）. 。您可以在 那tuto.
请注意，其余的 PEP 287
以下是用于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
"""
- 休息
如今，可能更普遍的格式是 重组文本 （休息）格式由 狮身人面像 生成文档。注意：默认情况下，它在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有自己的 格式 经常使用。它也可以通过狮身人面像解释（即使用 拿破仑插件).
例子：
"""
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建议自己遵循自己的 numpydoc 基于Google格式，由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
"""
转换/生成
可以使用类似的工具 py 要自动将Docstrings生成尚未记录的Python项目，或将现有Docstrings（可以将几种格式混合）从一种格式转换为另一种格式。
注意：示例是从 PYMENT文档
其他提示
这 Google样式指南 包含出色的Python样式指南。这包括 可读docstring语法的约定 这提供了比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
我喜欢将其扩展为也包括在参数中包含类型信息，如此处所述 狮身人面像文档教程. 。例如：
def add_value(self, value):
"""Add a new value.
Args:
value (str): the value to add.
"""
pass
docstring约定 PEP-257 比PEP-8更细节。
但是，docstrings似乎比其他代码的其他领域更为个性化。不同的项目将有自己的标准。
我倾向于始终包含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
这意味着我发现像这样开始的docstrings凌乱。
def sq(n):
"""Return the squared result.
...
显然没有人提到它：您也可以使用 Numpy Docstring标准. 。它被广泛用于科学界。
- 这 格式的规格 从numpy和一个 例子
- 您有一个狮身人面像扩展以渲染它： numpydoc
- 还有一个例子说明了渲染的docstring看起来多么美丽： http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html
解析Google风格的Docstrings的Napolean sphinx扩展（在@nathan的答案中推荐）也支持Numpy风格的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
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
是python； 什么都行. 。考虑如何 发布您的文档. 。除了源代码的读者外，Docstrings是看不见的。
人们真的喜欢在网络上浏览和搜索文档。为此，请使用文档工具 狮身人面像. 。这是记录Python项目的事实上的标准。产品很漂亮 - 看看 https://python-guide.readthedocs.org/en/latest/ 。网站 阅读文档 将免费托管您的文档。
我建议使用Vladimir Keleshev的 PEP257 Python程序以检查您的docstrings PEP-257 和 Numpy Docstring标准 用于描述参数，返回等。
PEP257将报告您与标准的分歧，被称为Pylint和Pep8。
