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

解决方法:

格式

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

– 谷歌

谷歌有自己经常使用的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建议您遵循自己的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
"""

转换/生成

可以使用像Pyment这样的工具自动生成尚未记录的Python项目的文档字符串,或者将现有文档字符串(可以混合多种格式)从格式转换为另一种格式.

注意：示例来自Pyment documentation