2017-8-31 自动 生成注释文档（docstring）

情景描述：

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

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

# 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 git@github.com: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文档。