我已经看到了几种用Python编写文档字符串的样式,是否有正式或“同意的”样式?
epydoc
,doxygen
,sphinx
?没有人有任何统计资料,在这样的情况下,太多的选择可能会受到伤害,其中一个会取代其他统计吗?
def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""
我已经看到了几种用Python编写文档字符串的样式,是否有正式或“同意的”样式?
epydoc
,doxygen
,sphinx
?没有人有任何统计资料,在这样的情况下,太多的选择可能会受到伤害,其中一个会取代其他统计吗?
def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""
Answers:
可以按照其他文章所示的几种格式编写Python文档字符串。但是未提及默认的Sphinx文档字符串格式,该格式基于reStructuredText(reST)。您可以在此博客文章中获得有关主要格式的一些信息。
请注意,reST是PEP 287推荐的
以下是文档字符串的主要使用格式。
从历史上看,像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中使用它(在定义方法后键入三引号,然后按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有自己常用的格式。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.
"""
甚至更多的例子
请注意,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文档
在谷歌的风格指南中包含一个优秀的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
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.
...
"""Return the squared result"""
而不是"""Returns the squared result"""
。尽管个人而言,尽管PEP说了什么,但我还是写了Tim的情况。
显然没有人提到它:您还可以使用Numpy Docstring Standard。它在科学界被广泛使用。
用于解析Google样式文档字符串的Napolean狮身人面像扩展名(在@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
是Python;一切顺利。考虑如何发布您的文档。除了您的源代码读者以外,文档字符串是不可见的。
人们真的很喜欢浏览和搜索网络上的文档。为此,请使用文档工具Sphinx。这是记录Python项目的实际标准。该产品非常漂亮-请访问https://python-guide.readthedocs.org/en/latest/。“ 阅读文档 ”网站将免费托管您的文档。
ipython
来测试驱动一个库,这使得读取文档字符串变得非常简单—我所要输入的只是your_module.some_method_im_curious_about?
得到的每一个漂亮的打印输出,包括文档字符串。
help
在记录的函数/方法/类上运行该函数,则会看到docstring (即使您只能访问已编译的模块,也可以执行此操作)。我个人认为选择文档字符串约定时应牢记这一点(即,应按原样阅读)。
我建议使用Vladimir Keleshev的pep257 Python程序根据PEP-257和Numpy Docstring Standard检查您的文档字符串,以描述参数,返回值等。
pep257将报告您与标准的差异,称为pylint和pep8。
pydocstyle --select=D4 tmp.py
检查一系列文档字符串内容问题,包括节命名。