pydoc用法

pydoc是python自帶的一個文檔生成工具，使用pydoc能夠很方便的查看類和方法結構

 

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

 

1、查看文檔的方法

方法1：啓動本地服務，在web上查看文檔

命令【python3 -m pydoc -p 1234】

 

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

 

說明：

一、-p指定啓動的服務的端口號，能夠隨意指定不衝突的端口號

二、只有在自建的工程根目錄下使用該命令，才能看到當前工程下全部的內容，不然只能看到python環境變量下的模塊內容

三、若是本地只有一個python，能夠直接使用【pydoc -p 端口號】啓動，但由於我本地有python2和python3，因此指定了用python3

方法2：直接查看某個py文件的內容 

例子：新建了一個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 目錄名】生成文檔

 

說明：若是是將整個目錄生成這種格式，不建議用這種方式，由於若是他展現目錄下的子文件的說明時，會去子目錄下找對應.html文件，若是文件不存在，就會404

 

方法四：-k查找模塊

py經過-k查找模塊，會在當前工程目錄以及python環境變量目錄下查找包含關鍵詞的模塊信息 

【python3 -m pydoc -k 關鍵詞】

 

例如以下命令：

python3 -m pydoc -k  testpydoc

 

結果以下：

testpydoc - @author 天天1990

2、html文檔說明 

經過查看文檔的方法，咱們能夠看到在html的文檔主要分紅四部分：py文件的頂部註釋、Classes、Functions、Data

（示例代碼見結尾部分）

第一部分：模塊的文檔說明，展現模塊頂部的多行註釋

註釋內若是包含了模塊文件內的class名，或方法名()，則顯示藍色，且能夠點擊跳轉到對應說明位置

 

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

1.只能展現class下的註釋，不會展現class下方法的註釋

2.class上面有#註釋時，展現#號的註釋

3.class下有」」」多行註釋」」」時優先展現多行註釋，就不展現頂部的#號的註釋了

 

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

1.function上面有#註釋時，展現#號的註釋

2.function下有」」」多行註釋」」」時優先展現多行註釋，就不展現頂部的#號的註釋了

 

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

 

示例代碼：

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

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

Data：a，b
"""

#註釋放在方法名前，使用#號註釋
def test1(a):
    print("註釋放在方法名前")

#註釋放在方法名前，使用#號註釋
def test2():
    """
    註釋放在方法內的第一行，既有#號又有多行註釋時，優先展現多行註釋
    """
    print("既有#號又有多行註釋時，優先展現多行註釋 ")

def test3():
    #在方法第一行內使用#註釋
    print("在方法內使用#號註釋，不生效")

class testclass():
    """
    註釋生效順序與方法一致，優先展現類下的多行註釋，若是沒有才展現類上面的#號註釋
    類下的方法的註釋不會展現出來
    """
    def function1(self):#類下方法的註釋不會展現
        print("類下的第一個方法")
    def function2(self,a):
        print("類下的第二個參數，包含a參數")


a=1#變量的註釋不會展現出來
b=2

3、註釋方法

經過上面的文檔說明，咱們能夠合理的註釋，有助於瞭解工程結構

python的註釋方法有兩種：

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

#單行註釋

 

2.多行註釋：使用三個雙引號或單引號來註釋多行內容

'''
單引號進行多行註釋

'''

 

"""

雙引號進行多行註釋

"""

pydoc註釋展現策略：

在functions和classes前面加#註釋，或者在function和class第一行內加三個單引號或三個雙引號進行註釋

若是有三個引號的註釋方法，會優先使用三個點的註釋，其次才展現#號的註釋

 

注意：若是在方法或class定義後第一行使用#註釋是拉取不到註釋的

 

例子1：class前有#號註釋，class內有多行註釋，pydoc會優先展現三個點內的註釋

 

例子2：方法內使用#號註釋，pydoc不會顯示註釋內容（class同理）

 

例子3：方法或class沒有多行註釋，只在方法外有#號註釋時，會展現定義前的#號內的內容

 

例子4：模塊頂部的內容，優先展現多行註釋中的內容