什麼是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:

看效果： 

https://www.jb51.net/article/86757.htm