Python中的多行注釋文檔編寫(xiě)風(fēng)格匯總
什么是docstring
在軟件工程中，其實(shí)編碼所占的部分是非常小的，大多是其它的事情，比如寫(xiě)文檔。文檔是溝通的工具。
在Python中，比較推崇在代碼中寫(xiě)文檔，代碼即文檔，比較方便，容易維護(hù)，直觀，一致。
代碼寫(xiě)完，文檔也出來(lái)了。其實(shí)Markdown也差不多這種思想，文本寫(xiě)完，排版也完成了。
看看PEP 0257中對(duì)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.
簡(jiǎn)單來(lái)說(shuō)，就是出現(xiàn)在模塊、函數(shù)、類、方法里第一個(gè)語(yǔ)句的，就是docstring。會(huì)自動(dòng)變成屬性__doc__。
def foo(): """ This is function foo"""
可通過(guò)foo.__doc__訪問(wèn)得到' This is function foo'.
各類docstring風(fēng)格：
Epytext
這是曾經(jīng)比較流行的一直類似于javadoc的風(fēng)格。
""" 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
這是現(xiàn)在流行的一種風(fēng)格，reST風(fēng)格，Sphinx的御用格式。我個(gè)人也是喜歡用這種風(fēng)格，比較緊湊。
""" 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風(fēng)格
""" 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風(fēng)格)
"""
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工具之第三方庫(kù)pyment
用來(lái)創(chuàng)建和轉(zhuǎn)換docstring.
使用方法就是用pyment生成一個(gè)patch，然后打patch。
$ pyment test.py #生成patch $ patch -p1 < test.py.patch #打patch
詳情：https://github.com/dadadel/pyment
使用sphinx的autodoc自動(dòng)從docstring生產(chǎn)api文檔，不用再手寫(xiě)一遍
我在代碼中已經(jīng)寫(xiě)過(guò)docstring了，寫(xiě)api文檔的內(nèi)容跟這個(gè)差不多，難道要一個(gè)一個(gè)拷貝過(guò)去rst嗎？當(dāng)然不用。sphinx有autodoc功能。
首先編輯conf.py文件，
1. 要有'sphinx.ext.autodoc'這個(gè)extensions
2. 確保需要自動(dòng)生成文檔的模塊可被import，即在路徑中。比如可能需要sys.path.insert(0, os.path.abspath(‘../..'))
然后，編寫(xiě)rst文件，
xxx_api module --------------------- .. automodule:: xxx_api :members: :undoc-members: :show-inheritance:
看效果：
相關(guān)文章
Python中將圖像轉(zhuǎn)換為PDF的方法實(shí)現(xiàn)
本文主要介紹了Python中將圖像轉(zhuǎn)換為PDF的方法實(shí)現(xiàn),主要使用img2pdf和PyPDF2軟件包,具有一定的參考價(jià)值,感興趣的可以了解一下2023-08-08
這篇文章主要介紹了如何在python中寫(xiě)hive腳本,文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2019-11-11
python訪問(wèn)純真IP數(shù)據(jù)庫(kù)的代碼
項(xiàng)目中有這樣的需求，通過(guò)IP地址判斷客戶端是網(wǎng)通的還是電信的。從同事那拿了個(gè)純文本的IP純真數(shù)據(jù)庫(kù)，用Python寫(xiě)了一個(gè)小程序，感覺(jué)挺好的。2011-05-05
爬蟲(chóng)框架 Feapder 和 Scrapy 的對(duì)比分析
本篇文章在源碼層面比對(duì) feapder、scrapy 、scrapy-redis 的設(shè)計(jì)，閱讀本文后，會(huì)加深您對(duì) scrapy 以及 feapder 的了解，以及為什么推薦使用 feapder,剛興趣的朋友可以參考下面文章內(nèi)容2021-09-09
Pandas進(jìn)行數(shù)據(jù)編碼的十種方式總結(jié)
在機(jī)器學(xué)習(xí)中，很多算法都需要我們對(duì)分類特征進(jìn)行轉(zhuǎn)換（編碼），即根據(jù)某一列的值，新增（修改）一列。本文為大家總結(jié)了Pandas中十種數(shù)據(jù)編碼的方式，需要的可以參考一下2022-04-04
python使用pandas讀寫(xiě)excel文件的方法實(shí)例
pandas是一個(gè)十分強(qiáng)大的數(shù)據(jù)處理工具,最近需要處理數(shù)據(jù)并輸入到excel,簡(jiǎn)單列舉它的用法,這篇文章主要給大家介紹了關(guān)于python使用pandas讀寫(xiě)excel文件的相關(guān)資料,文中通過(guò)實(shí)例代碼介紹的非常詳細(xì),需要的朋友可以參考下2022-08-08
如何將一個(gè)CSV格式的文件分割成兩個(gè)CSV文件
這篇文章主要介紹了如何將一個(gè)CSV格式的文件分割成兩個(gè)CSV文件，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2022-07-07
Python使用latexify模塊實(shí)現(xiàn)將代碼為數(shù)學(xué)公式
latexify 是一個(gè)輕量級(jí)的 Python 模塊,可以將 Python 代碼轉(zhuǎn)換為 LaTeX 格式的數(shù)學(xué)表達(dá)式,這篇文章就來(lái)和大家探索一下如何使用latexify模塊實(shí)現(xiàn)將代碼為數(shù)學(xué)公式吧2023-12-12
這篇文章主要介紹了python裝飾器實(shí)例大詳解,非常不錯(cuò)，具有參考借鑒價(jià)值，需要的朋友可以參考下2017-10-10
Python查找算法之分塊查找算法的實(shí)現(xiàn)
這篇文章主要介紹了Python查找算法之分塊查找算法的實(shí)現(xiàn)，文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧2021-04-04