Python中的多行注釋文檔編寫風格匯總
什么是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.
簡單來說，就是出現(xiàn)在模塊、函數(shù)、類、方法里第一個語句的，就是docstring。會自動變成屬性__doc__。
def foo(): """ This is function foo"""
可通過foo.__doc__訪問得到' This is function foo'.
各類docstring風格：
Epytext
這是曾經(jīng)比較流行的一直類似于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
這是現(xiàn)在流行的一種風格，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
用來創(chuàng)建和轉(zhuǎn)換docstring.
使用方法就是用pyment生成一個patch，然后打patch。
$ pyment test.py #生成patch $ patch -p1 < test.py.patch #打patch
詳情：https://github.com/dadadel/pyment
使用sphinx的autodoc自動從docstring生產(chǎn)api文檔，不用再手寫一遍
我在代碼中已經(jīng)寫過docstring了，寫api文檔的內(nèi)容跟這個差不多，難道要一個一個拷貝過去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:
看效果：
相關文章
Python中將圖像轉(zhuǎn)換為PDF的方法實現(xiàn)
本文主要介紹了Python中將圖像轉(zhuǎn)換為PDF的方法實現(xiàn),主要使用img2pdf和PyPDF2軟件包,具有一定的參考價值,感興趣的可以了解一下2023-08-08
這篇文章主要介紹了如何在python中寫hive腳本,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下2019-11-11
項目中有這樣的需求，通過IP地址判斷客戶端是網(wǎng)通的還是電信的。從同事那拿了個純文本的IP純真數(shù)據(jù)庫，用Python寫了一個小程序，感覺挺好的。2011-05-05
本篇文章在源碼層面比對 feapder、scrapy 、scrapy-redis 的設計，閱讀本文后，會加深您對 scrapy 以及 feapder 的了解，以及為什么推薦使用 feapder,剛興趣的朋友可以參考下面文章內(nèi)容2021-09-09
在機器學習中，很多算法都需要我們對分類特征進行轉(zhuǎn)換（編碼），即根據(jù)某一列的值，新增（修改）一列。本文為大家總結了Pandas中十種數(shù)據(jù)編碼的方式，需要的可以參考一下2022-04-04
pandas是一個十分強大的數(shù)據(jù)處理工具,最近需要處理數(shù)據(jù)并輸入到excel,簡單列舉它的用法,這篇文章主要給大家介紹了關于python使用pandas讀寫excel文件的相關資料,文中通過實例代碼介紹的非常詳細,需要的朋友可以參考下2022-08-08
這篇文章主要介紹了如何將一個CSV格式的文件分割成兩個CSV文件，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-07-07
Python使用latexify模塊實現(xiàn)將代碼為數(shù)學公式
latexify 是一個輕量級的 Python 模塊,可以將 Python 代碼轉(zhuǎn)換為 LaTeX 格式的數(shù)學表達式,這篇文章就來和大家探索一下如何使用latexify模塊實現(xiàn)將代碼為數(shù)學公式吧2023-12-12
這篇文章主要介紹了python裝飾器實例大詳解,非常不錯，具有參考借鑒價值，需要的朋友可以參考下2017-10-10
這篇文章主要介紹了Python查找算法之分塊查找算法的實現(xiàn)，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2021-04-04