什么是docstring
在软件工程中，其实编码所占的部分是非常小的，大多是其它的事情，比如写文档。文档是沟通的工具。 在python中，比较推崇在代码中写文档，代码即文档，比较方便，容易维护，直观，一致。 代码写完，文档也出来了。其实markdown也差不多这种思想，文本写完，排版也完成了。 看看pep 0257中对docstring的定义：
a docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. such a docstring becomes the __doc__ special attribute of that object.简单来说，就是出现在模块、函数、类、方法里第一个语句的，就是docstring。会自动变成属性__doc__。
def foo():
“”” this is function foo”””
可通过foo.__doc__访问得到’ this is function foo’.
各类docstring风格：
epytext
这是曾经比较流行的一直类似于javadoc的风格。
“””
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
这是现在流行的一种风格，rest风格，sphinx的御用格式。我个人也是喜欢用这种风格，比较紧凑。
“””
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 a groups style docs.
parameters:
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风格)
“””
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
“””
docstring工具之第三方库pyment
用来创建和转换docstring. 使用方法就是用pyment生成一个patch，然后打patch。
$ pyment test.py #生成patch
$ patch -p1 < test.py.patch #打patch
详情：https://github.com/dadadel/pyment
使用sphinx的autodoc自动从docstring生产api文档，不用再手写一遍
我在代码中已经写过docstring了，写api文档的内容跟这个差不多，难道要一个一个拷贝过去rst吗？当然不用。sphinx有autodoc功能。 首先编辑conf.py文件， 1. 要有’sphinx.ext.autodoc’这个extensions 2. 确保需要自动生成文档的模块可被import，即在路径中。比如可能需要sys.path.insert(0, os.path.abspath(‘../..’))
然后，编写rst文件，
xxx_api module
———————
.. automodule:: xxx_api
:members:
:undoc-members:
:show-inheritance:
敲make html命令，就可以从docstring中生成相关的文档了，不用多手写一遍rst. 看效果：
更多python中的多行注释文档编写风格相关文章请关注php中文网！