【推荐】2019 Java 开发者跳槽指南.pdf(吐血整理) >>> 
想改善这个问题吗？ 更新问题，以便通过编辑此帖子以事实和引用的形式回答。
去年关闭。
我已经看到了几种用Python编写文档字符串的不同样式，是否有正式的或“同意的”样式？
#1楼
是Python； 一切顺利 。 考虑如何发布您的文档 。 除了您的源代码读者以外，文档字符串是不可见的。
人们真的很喜欢浏览和搜索网络上的文档。 为此，请使用文档工具Sphinx 。 这是记录Python项目的实际标准。 该产品非常漂亮-请看https://python-guide.readthedocs.org/en/latest/ 。 “ 阅读文档 ”网站将免费托管您的文档。
#2楼
显然没有人提到它：您还可以使用Numpy Docstring Standard 。 它在科学界被广泛使用。
- numpy 格式的说明以及 示例
- 您有一个狮身人面像扩展程序来渲染它： numpydoc
- 还有一个呈现的文档字符串看起来如何美丽的示例： http : //docs.scipy.org/doc/numpy/reference/generation/numpy.mean.html
用于解析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
#3楼
格式
可以按照其他文章所示的几种格式编写Python文档字符串。 但是，未提及默认的Sphinx文档字符串格式，该格式基于reStructuredText（reST） 。 您可以在此博客文章中获得有关主要格式的一些信息。
请注意，reST是PEP 287推荐的
以下是文档字符串的主要使用格式。
-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有自己常用的格式 。 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.
"""
甚至更多的例子
-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文档
#4楼
我建议使用Vladimir Keleshev的pep257 Python程序根据PEP-257和Numpy Docstring标准检查您的文档字符串，以描述参数，返回值等。
pep257将报告您与标准的差异，称为pylint和pep8。
#5楼
PEP-8是官方的python编码标准。 它包含有关文档字符串的部分，该部分引用了PEP- 257-文档字符串的完整规范。
来源：oschina
链接：https://my.oschina.net/stackoom/blog/3144519