我在Python中看到过几种不同的写作文档字符样式,是官方还是"同意"的风格？
Python文档字符串可以按照其他帖子显示的几种格式编写.但是没有提到默认的Sphinx文档字符串格式,它基于reStructuredText(reST).您可以获得有关该tuto中主要格式的一些信息.
请注意,PEP 287建议使用reST
接下来是docstrings的主要使用格式.
从历史上看,类似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 """
谷歌有自己经常使用的格式.它也可以由Sphinx解释(即使用拿破仑插件).
例:
"""
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风格指南.它包含可读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
我喜欢扩展它以在参数中包含类型信息,如本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.
...
显然没有人提到它:你也可以使用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
PEP-8是官方的python编码标准.它包含一个关于docstrings的部分,它引用了PEP-257--一个完整的docstrings规范.
这是Python; 什么都行.考虑如何发布您的文档.除了源代码的读者之外,文档字符串是不可见的.
人们非常喜欢在网上浏览和搜索文档.为此,请使用文档工具Sphinx.它是记录Python项目的事实上的标准.产品很漂亮 - 看看https://python-guide.readthedocs.org/en/latest/.阅读文档的网站将免费托管您的文档.
我建议使用Vladimir Keleshev的pep257 Python程序根据PEP-257和Numpy Docstring Standard检查您的文档字符串，以描述参数，返回值等。
pep257将报告您与标准的差异，称为pylint和pep8。
京公网安备 11010802040832号 | 京ICP备19059560号-6 