情景描述：

项目中，发现很多函数、类没有注释说明，一个个弄比较繁琐，所以……

<!--more-->

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； 人话：“出现在模块、函数、类、方法里的第一个语句，就叫做docsting”； 调用：使用__doc__。

def foo():
  """ This is function foo"""

foo.doc

This is function foo

### `docstring`风格：
> 主要四种：`javadoc`(`Epytext`), `reST`, `numpydoc`, `google`

```python
# 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（推荐，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
"""

转换工具pyment

用来创建、转换docsting，点击查看安装 centos中可能使用不了patch，点击下载安装包 pyment命令帮助：pyment -h

# 安装pyment
$ git clone https://github.com/dadadel/pyment.git  # or [email protected]:dadadel/pyment.git
$ cd pyment
$ python setup.py install

# 安装patch
# 下载安装包：http://centos-packages.com/7/package/patch/
rpm -i patch-2.7.1-8.el7.x86_64.rpm

# 使用方法
$ pyment test.py      #生成patch
$ patch -p1 < test.py.patch #打patch

例子：

注释前

test.py

def func(param1=True, param2='default val'): '''Description of func with docstring groups style.

Params:
    param1 - descr of param1 that has True for default value.
    param2 - descr of param2

Returns:
    some value

Raises:
    keyError: raises key exception
    TypeError: raises type exception

'''
pass

class A: def method(self, param1, param2=None): pass

>执行`pyment test.py`，得到`patch`文件

Patch generated by Pyment v0.2.0

--- a/test.py +++ b/test.py @@ -1,20 +1,22 @@ def func(param1=True, param2='default val'):

• '''Description of func with docstring groups style.

• """Description of func with docstring groups style.

• Params:

• param1 - descr of param1 that has True for default value.

• param2 - descr of param2

• :param param1: descr of param1 that has True for default value

• :param param2: descr of param2 (Default value = 'default val')

• :returns: some value

• :raises keyError: raises key exception

• :raises TypeError: raises type exception

• Returns:

• some value

• Raises:

• keyError: raises key exception

• TypeError: raises type exception

• '''

• """ pass

  class A:

• """ """ def method(self, param1, param2=None):

• """

• :param param1:

• :param param2: (Default value = None)

• """ pass

  >执行`patch -p1 < test.py.patch`，注释后得到
  

def func(param1=True, param2='default val'):
    """Description of func with docstring groups style.

    :param param1: descr of param1 that has True for default value
    :param param2: descr of param2 (Default value = 'default val')
    :returns: some value
    :raises keyError: raises key exception
    :raises TypeError: raises type exception

    """
    pass

class A:
    """ """
    def method(self, param1, param2=None):
        """

        :param param1:
        :param param2:  (Default value = None)

        """
        pass

后续

使用sphinx的autodoc自动从docstring生产api文档, 避免重复工作，再娄一遍Api文档。