pydoc是python自帶的一個文檔生成工具，使用pydoc可以很方便的查看類和方法結(jié)構(gòu)

本文主要介紹：1.查看文檔的方法、2.html文檔說明、3.注釋方法、

一、查看文檔的方法

**方法1：**啟動本地服務(wù)，在web上查看文檔

命令【python3 -m pydoc -p 1234】

通過http://localhost:1234來訪問查看文檔

說明：

1、-p指定啟動的服務(wù)的端口號，可以隨意指定不沖突的端口號

2、只有在自建的工程根目錄下使用該命令，才能看到當前工程下所有的內(nèi)容，否則只能看到python環(huán)境變量下的模塊內(nèi)容

3、如果本地只有一個python，可以直接使用【pydoc -p 端口號】啟動，但因為我本地有python2和python3，所以指定了用python3

**方法2：**直接查看某個py文件的內(nèi)容

例子：新建了一個py文件叫做testpydoc.py，進入testpydoc.py所在目錄

python3 -m pydoc testpydoc

**方法三：**生成html說明文檔

例子：新建了一個py文件叫做testpydoc.py，進入testpydoc.py所在目錄

python3 -m pydoc -w testpydoc

會默認將當前目錄下的testpydoc生成一個叫做testpydoc.html的文檔，如果是目錄直接【python3 -m pydoc -w 目錄名】生成文檔

說明：如果是將整個目錄生成這種格式，不建議用這種方式，因為如果他展示目錄下的子文件的說明時，會去子目錄下找對應(yīng).html文件，如果文件不存在，就會404

方法四：-k查找模塊

py通過-k查找模塊，會在當前工程目錄以及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名，或方法名()，則顯示藍色，且可以點擊跳轉(zhuǎn)到對應(yīng)說明位置

第二部分：classes，展示class以及class下的function

1.只能展示class下的注釋，不會展示class下方法的注釋

2.class上面有#注釋時，展示#號的注釋

3.class下有”””多行注釋”””時優(yōu)先展示多行注釋，就不展示頂部的#號的注釋了

第三部分：function，模塊下的def方法，不是class中的方法

1.function上面有#注釋時，展示#號的注釋

2.function下有”””多行注釋”””時優(yōu)先展示多行注釋，就不展示頂部的#號的注釋了

第四部分：data，模塊下直接定義的變量，不是function或class的變量

示例代碼：

“”"
@author 每天1990
@desc 本模塊是一個測試文件，用來說明pydoc的讀取內(nèi)容
@date 2017/4/13
說明：
classes:testclass()，具有function1()和function2()兩個方法

function：test1()，test2()，test3()

Data：a，b
“”"

#注釋放在方法名前，使用#號注釋
def test1(a):
print(“注釋放在方法名前”)

#注釋放在方法名前，使用#號注釋
def test2():
“”"
注釋放在方法內(nèi)的第一行，既有#號又有多行注釋時，優(yōu)先展示多行注釋
“”"
print("既有#號又有多行注釋時，優(yōu)先展示多行注釋 ")

def test3():
#在方法第一行內(nèi)使用#注釋
print(“在方法內(nèi)使用#號注釋，不生效”)

class testclass():
“”"
注釋生效順序與方法一致，優(yōu)先展示類下的多行注釋，如果沒有才展示類上面的#號注釋
類下的方法的注釋不會展示出來
“”"
def function1(self):#類下方法的注釋不會展示
print(“類下的第一個方法”)
def function2(self,a):
print(“類下的第二個參數(shù)，包含a參數(shù)”)

a=1#變量的注釋不會展示出來
b=2

三、注釋方法

通過上面的文檔說明，我們可以合理的注釋，有助于了解工程結(jié)構(gòu)

python的注釋方法有兩種：

1.單行注釋：使用#號進行注釋

#單行注釋

2.多行注釋：使用三個雙引號或單引號來注釋多行內(nèi)容

‘’’
單引號進行多行注釋

‘’’

“”"

雙引號進行多行注釋

“”"

pydoc注釋展示策略：

在functions和classes前面加#注釋，或者在function和class第一行內(nèi)加三個單引號或三個雙引號進行注釋

如果有三個引號的注釋方法，會優(yōu)先使用三個點的注釋，其次才展示#號的注釋

注意：如果在方法或class定義后第一行使用#注釋是拉取不到注釋的

例子1：class前有#號注釋，class內(nèi)有多行注釋，pydoc會優(yōu)先展示三個點內(nèi)的注釋

例子2：方法內(nèi)使用#號注釋，pydoc不會顯示注釋內(nèi)容（class同理）

例子3：方法或class沒有多行注釋，只在方法外有#號注釋時，會展示定義前的#號內(nèi)的內(nèi)容

例子4：模塊頂部的內(nèi)容，優(yōu)先展示多行注釋中的內(nèi)容