pydoc是python自帶的一個(gè)文檔生成工具,使用pydoc可以很方便的查看類和方法結(jié)構(gòu),pydoc模塊可以從python代碼中獲取docstring,然后生成幫助信息。
pydoc是Python自帶的模塊然眼,主要用于從python模塊中自動(dòng)生成文檔,這些文檔可以基于文本呈現(xiàn)的幔欧、也可以生成WEB頁面的罪治,還可以在服務(wù)器上以瀏覽器的方式呈現(xiàn)!
python -m pydoc -p 1234 ? ??在本地機(jī)器上礁蔗,按照給定的端口啟動(dòng)HTTP
一觉义、查看文檔的方法
方法1:啟動(dòng)本地服務(wù),在web上查看文檔
python3 -m pydoc -p 1234
通過http://localhost:1234來訪問查看文檔
說明:
1浴井、-p指定啟動(dòng)的服務(wù)的端口號晒骇,可以隨意指定不沖突的端口號
2、只有在自建的工程根目錄下使用該命令,才能看到當(dāng)前工程下所有的內(nèi)容洪囤,否則只能看到python環(huán)境變量下的模塊內(nèi)容
3徒坡、如果本地只有一個(gè)python,可以直接使用【pydoc -p 端口號】啟動(dòng)瘤缩,但因?yàn)槲冶镜赜衟ython2和python3喇完,所以指定了用python3
方法2:直接查看某個(gè)py文件的內(nèi)容
例子:新建了一個(gè)py文件叫做testpydoc.py,進(jìn)入testpydoc.py所在目錄
python3 -m pydoc testpydoc
方法三:生成html說明文檔
例子:新建了一個(gè)py文件叫做testpydoc.py剥啤,進(jìn)入testpydoc.py所在目錄
python3 -m pydoc -w?testpydoc
會默認(rèn)將當(dāng)前目錄下的testpydoc生成一個(gè)叫做testpydoc.html的文檔锦溪,如果是目錄直接【python3 -m pydoc -w 目錄名】生成文檔
說明:如果是將整個(gè)目錄生成這種格式,不建議用這種方式府怯,因?yàn)槿绻故灸夸浵碌淖游募恼f明時(shí)刻诊,會去子目錄下找對應(yīng).html文件,如果文件不存在牺丙,就會404
方法四:-k查找模塊
py通過-k查找模塊则涯,會在當(dāng)前工程目錄以及python環(huán)境變量目錄下查找包含關(guān)鍵詞的模塊信息?
【python3 -m pydoc -k 關(guān)鍵詞】
例如如下命令:
python3 -m pydoc -k? testpydoc
結(jié)果如下:
testpydoc - @author 每天1990
二、html文檔說明?
通過查看文檔的方法冲簿,我們可以看到在html的文檔主要分成四部分:py文件的頂部注釋粟判、Classes、Functions民假、Data
(示例代碼見結(jié)尾部分)
第一部分:模塊的文檔說明浮入,展示模塊頂部的多行注釋
注釋內(nèi)如果包含了模塊文件內(nèi)的class名龙优,或方法名()羊异,則顯示藍(lán)色,且可以點(diǎn)擊跳轉(zhuǎn)到對應(yīng)說明位置
第二部分:classes彤断,展示class以及class下的function
1.只能展示class下的注釋野舶,不會展示class下方法的注釋
2.class上面有#注釋時(shí),展示#號的注釋
3.class下有”””多行注釋”””時(shí)優(yōu)先展示多行注釋宰衙,就不展示頂部的#號的注釋了
need-to-insert-img
第三部分:function平道,模塊下的def方法,不是class中的方法
1.function上面有#注釋時(shí)供炼,展示#號的注釋
2.function下有”””多行注釋”””時(shí)優(yōu)先展示多行注釋一屋,就不展示頂部的#號的注釋了
第四部分:data,模塊下直接定義的變量袋哼,不是function或class的變量
示例代碼:
"""
@author?每天1990
@desc?本模塊是一個(gè)測試文件冀墨,用來說明pydoc的讀取內(nèi)容
@date?2017/4/13
說明:
classes:testclass(),具有function1()和function2()兩個(gè)方法
function:test1()涛贯,test2()诽嘉,test3()
Data:a,b
"""
#注釋放在方法名前,使用#號注釋
def?test1(a):
print("注釋放在方法名前")
#注釋放在方法名前虫腋,使用#號注釋
def?test2():
"""
注釋放在方法內(nèi)的第一行骄酗,既有#號又有多行注釋時(shí),優(yōu)先展示多行注釋
"""
print("既有#號又有多行注釋時(shí)悦冀,優(yōu)先展示多行注釋?")
def?test3():
#在方法第一行內(nèi)使用#注釋
print("在方法內(nèi)使用#號注釋趋翻,不生效")
class?testclass():
"""
注釋生效順序與方法一致,優(yōu)先展示類下的多行注釋盒蟆,如果沒有才展示類上面的#號注釋
類下的方法的注釋不會展示出來
"""
def?function1(self):#類下方法的注釋不會展示
print("類下的第一個(gè)方法")
def?function2(self,a):
print("類下的第二個(gè)參數(shù)嘿歌,包含a參數(shù)")
a=1#變量的注釋不會展示出來
b=2
三、注釋方法
通過上面的文檔說明茁影,我們可以合理的注釋宙帝,有助于了解工程結(jié)構(gòu)
python的注釋方法有兩種:
1.單行注釋:使用#號進(jìn)行注釋
#單行注釋
2.多行注釋:使用三個(gè)雙引號或單引號來注釋多行內(nèi)容
'''
單引號進(jìn)行多行注釋
'''
"""
雙引號進(jìn)行多行注釋
"""
pydoc注釋展示策略:
在functions和classes前面加#注釋,或者在function和class第一行內(nèi)加三個(gè)單引號或三個(gè)雙引號進(jìn)行注釋
如果有三個(gè)引號的注釋方法募闲,會優(yōu)先使用三個(gè)點(diǎn)的注釋步脓,其次才展示#號的注釋
注意:如果在方法或class定義后第一行使用#注釋是拉取不到注釋的
例子1:class前有#號注釋,class內(nèi)有多行注釋浩螺,pydoc會優(yōu)先展示三個(gè)點(diǎn)內(nèi)的注釋
例子2:方法內(nèi)使用#號注釋靴患,pydoc不會顯示注釋內(nèi)容(class同理)
例子3:方法或class沒有多行注釋,只在方法外有#號注釋時(shí)要出,會展示定義前的#號內(nèi)的內(nèi)容
例子4:模塊頂部的內(nèi)容鸳君,優(yōu)先展示多行注釋中的內(nèi)容