Python pydoc模組詳解：檢視、生成幫助檔案

前面講過，在建立函數、類以及類方法時，可以為它們新增說明性文件，即分別在函數體、類體以及類方法內部的首行新增具有說明性的字串即可。例如：

#demo.py檔案
def display(add):
    '''
    這是一個函數
    '''
    print(add)
   
class my_cla:
    '''
    這是一個類
    '''
    def say(self,add):
        '''
        這是一個類實體方法
        '''
        print(add)

如上所示，我們分別建立了 display() 函數和 my_cla 類，該類中還包含一個 say() 實體方法，並且我們為它們設定了說明性文件。

在此基礎上，可以通過 help() 函數或者 __doc__ 屬性來呼叫函數、類或者類方法的說明性文件。例如在上面程式的基礎上，新增如下程式碼：

help(display)
help(my_cla)
help(my_cla.say)

執行程式，執行結果為：

Help on function display in module __main__:

display(add)
    這是一個函數

Help on class my_cla in module __main__:

class my_cla(builtins.object)
|  這是一個類
| 
|  Methods defined here:
| 
|  say(self, add)
|      這是一個類實體方法
| 
|  ----------------------------------------------------------------------
|  Data descriptors defined here:
| 
|  __dict__
|      dictionary for instance variables (if defined)
| 
|  __weakref__
|      list of weak references to the object (if defined)

Help on function say in module __main__:

say(self, add)
    這是一個類實體方法

顯然，我們調出了它們的說明性文件，但不得不說，該方法僅能通過編寫呼叫程式碼在輸出結果中檢視，不是很方便。

實際上，Python 還提供了 pydoc 模組，通過該模組可以快速地生成程式的幫助文件。接下來就詳細講解 pydoc 模組的用法。

pydoc在控制台中檢視文件

和 help() 及 __doc__ 不同，使用 pydoc 模組無需編寫任何 python 程式碼，通過執行 python 命令即可檢視程式中成員的說明性文件。

執行如下 Python 命令，即可在控制台檢視指定模組的說明性文件，命令語法格式如下：

python -m pydoc 模組名

其中，-m 表示執行指定模組，這裡表示要執行 pydoc 模組。注意在指定模組名時，除非其建立在 Python 直譯器能自行找到的目錄下，否則這裡要明確模組所在的位置。

以 demo.py 檔案為例，在控制台執行如下命令：

python -m pydoc demo

執行此命令，即可看到 demo.py 檔案中 display() 函數、my_cla 類以及該類中 say() 實體方法的說明性文件。讀者可自行執行該命令檢視輸出結果，這裡不再給出執行結果。

值得一提的是，使用該命令在控制台輸出執行模組的幫助資訊時，可能一屏無法顯示所有的資訊，我們可以通過捲動滑鼠滑輪或者按“空格”鍵來滑屏，檢視後續的資訊。

如果讀者執行該命令，可以看到，對於模組中各個成員的說明性文件，該命令有自己的組織方法，即總是按如下順序來顯示：

• 模組的文件說明：就是＊.py 檔案頂部的注釋資訊，這部分資訊會被提取成模組的文件說明。
• CLASSES ：列出該模組所包含的全部類。
• FUNCTIONS：列出該模組所包含的全部函數。
• DATA：列出該模組所包含的全部成員變數。
• FILE：顯示該模組對應的原始檔。

pydoc生成HTML文件

除此之外，pydoc 還可以將指定模組的幫助資訊提取出來，並自動組織成一個 HTML 文件。

使用 pydoc 模組生成 HTML 幫助文件的命令如下：

python -m pydoc -w 模組名

上面命令主要就是為 pydoc 模組額外指定了 -w 選項，該選項代表 write，表明輸出 HTML 文件。

例如，在 demo.py 所在當前目錄下執行如下命令：

python -m pydoc -w demo

執行上面命令，可以看到系統生成“wrote demo.html” 提示資訊。接下來可以在該目錄下發現額外生成了一個 demo.html 檔案，使用瀏覽器開啟該檔案，可以看到如圖 1 所示的頁面。

---