C語言中文網 目錄

Python pydoc模塊詳解:查看、生成幫助文檔

< 上一頁Python文檔和測試 Python doctest下一頁 >

前面己經介紹了為函數、類、方法等編寫文檔(只要在函數、類、方法定義后定義一個字符串即可)。前面也介紹了使用 help() 函數和 __doc__ 屬性來查看函數、類、方法的文檔,但這種方式總是在控制器中查看,有時候難免不太方便。

借助于 Python 自帶的 pydoc 模塊,可以非常方便地查看、生成幫助文檔,該文檔是 HTML 格式的,因此查看、使用起來非常方便。

這里先提供如下 Python 源文件(文件名為 fkmodule.py):
MY_NAME = 'C語言中文網'

def say_hi(name):
    '''
    定義一個打招呼的函數
    返回對指定用戶打招呼的字符串
    '''
    print("執行say_hi函數")
    return name + '您好!'
def print_rect(height, width):
    '''
    定義一個打印矩形的函數
    height - 代表矩形的高
    width - 代表矩形的寬
    '''
    print(('*' * width + '\n') * height)
class User:
    NATIONAL = 'China'
    '''
    定義一個代表用戶的類
    該類包括name、age兩個變量
    '''
    def __init__(self, name, age):
        '''
        name初始化該用戶的name
        age初始化該用戶的age
        '''
        self.name = name
        self.age = age
    def eat (food):
        '''
        定義用戶吃東西的方法
        food - 代表用戶正在吃的東西
        '''
        print('%s正在吃%s' % (self.name, food))
上面代碼定義了一個 fkmodule.py 源文件,也就是定義了一個 fkmodule 模塊,該模塊為函數、類和方法都提供了文檔說明。下面將會示范如何使用 pydoc 來查看、生成該模塊的文檔。

pydoc在控制臺中查看文檔

先看如何使用 pydoc 模塊在控制臺中查看 HTML 文檔。使用 pydoc 模塊在控制臺中查看幫助文檔的命令如下:

python -m pydoc 模塊名

上面命令中的 -m 是 python 命令的一個選項,表示運行指定模塊,此處表示運行 pydoc 模塊。后面的“模塊名”參數代表程序要查看的模塊。

例如,在 fkmodule.py 文件所在目錄下運行如下命令:

python -m pydoc fkmodule

上面命令表示使用 pydoc 查看 fkmodule 模塊的命令。運行該命令,將看到如圖 1 所示的輸出結果。


圖 1 使用 pydoc 模塊在控制臺中查看文檔

按下空格鍵,pydoc 將會使用第二屏來顯示文檔信息,如圖 2 所示。


圖 2 使用 pydoc 查看文檔的第二屏信息

從圖 1 可以看出,使用 pydoc 在控制臺中查看文檔時,由于一屏無法顯示所有的文檔信息,因此同樣需要以分屏的形式來顯示,這樣查看其實并不方便,與使用 help() 命令查看幫助信息的差別并不大。

當然,在使用 pydoc 查看幫助信息時,它會有自己的組織方式,它總是按如下順序來顯示模塊中的全部內容:
  • 模塊的文檔說明:就是*.py 文件頂部的注釋信息,這部分信息會被提取成模塊的文檔說明。
  • CLASSES 部分:這部分會列出該模塊所包含的全部類。
  • FUNCTIONS 部分:這部分會列出該模塊所包含的全部函數。
  • DATA 部分:這部分會列出該模塊所包含的全部成員變量。
  • FILE 部分:這部分會顯示該模塊對應的源文件。

不管怎么樣,直接在控制臺中查看指定模塊的幫助信息依然不太方便,下面將會使用 pydoc 來為指定模塊生成 HTML 文檔。

pydoc生成HTML文檔

使用 pydoc 模塊在控制臺中查看幫助文檔的命令如下:

python -m pydoc -w 模塊名

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

例如,在 fkmodule.py 所在當前目錄下運行如下命令:

python -m pydoc -w fkmodule

運行上面命令,可以看到系統生成“wrote fkmodule.html” 提示信息。接下來可以在該目錄下發現額外生成了一個 fkmodule.html 文件,使用瀏覽器打開該文件,可以看到如圖 3 所示的頁面。

使用 pydoc 生成的 HTML 文檔
圖 3 使用 pydoc 生成的 HTML 文檔

將圖 3 所示的頁面拉到下面,可以看到如圖 4 所示的頁面。

使用 pydoc 生成的文擋的第二屏信息
圖 4 使用 pydoc 生成的文擋的第二屏信息

從圖 3 和圖 4 所示的頁面來看,該 HTML 頁面與在控制臺中查看的文檔信息基本相同,區別在于,由于這是一個 HTML 頁面,因此用戶可以拖動滑塊來上、下滾動屏幕,以方便查看。

需要說明的是,pydoc 還可用于為指定目錄生成 HTML 文檔。例如,通過如下命令為指定目錄下的所有模塊生成 HTML 文檔:

python3 -m pydoc -w 目錄名

但上面命令有一個缺陷,那就是當該命令工具要展示目錄下子文件的說明時,會去子目錄下找對應的 .html 文件,如果文件不存在,就會顯示 404 錯誤。

如果真的要查看指定目錄下所有子目錄中的文檔信息,則建議啟動本地服務器來查看。

啟動本地服務器來查看文檔信息

啟動本地服務器來查看文檔信息,可以使用如下兩個命令:

python3 -m pydoc -p 端口號

在指定端口啟動 HTTP 服務器,接下來用戶可以通過瀏覽器來查看 Python 的所有模塊的文檔信息:

python3 -m pydoc -b

在任意一個未占用的端口啟動HTTP服務器,接下來用戶同樣可以通過瀏覽器來查看 Python 的所有模塊的文檔信息。

例如,在文件當前所在目錄下運行如下命令:

python -m pydoc -p 8899

該命令工具將會顯示如下輸出信息:

Server ready at http://localhost:8899/
Server commands: [b]rowser, [q]uit

上面的輸出信息提示 HTTP 服務器正在 8899 端口提供服務器,用戶可以輸入 b 命令來啟動瀏覽器(實際上用戶可以自行啟動瀏覽器),也可以輸入 q 命令來停止服務器。

打開瀏覽器訪問 http://localhost:8899/,將會看到如圖 5 所示的頁面。

模塊列表
圖 5 模塊列表

從圖 5 可以看出,該頁面默認顯示了當前 Python 的所有模塊。其中:
  • 第一部分顯示 Python 內置的核心模塊。
  • 第二部分顯示當前目錄下的所有模塊,此處顯示的就是 fkmodule 模塊。
  • 第三部分顯示 d:\python_module 目錄下的所有模塊,此時在該目錄下并未包含任何模塊。pydoc 之所以顯示該目錄,是因為本機配置了 PYTHONPATH 環境變量,其值為 .;d:\python_module,因此 pydoc 會自動顯示該目錄下的所有模塊。換而言之,第三部分用于顯示 PYTHONPATH 環境變量所指定路徑下的模塊。

如果讀者將圖 5 所示的頁面向下拉,將會依次看到 Python 系統在 D:\Python\Python36\DLLs、D:\Python\Python36\lib、D:\Python\Python36\lib\site-packages 路徑下的所有模塊。

如果要查看指定模塊,只要單擊圖 5 所示頁面中的模塊鏈接即可。例如,單擊圖 5 所示頁面中的“fkmodule”模塊鏈接,將會看到如圖 6 所示的頁面。


圖 6 通過服務器查看 fkmodule 模塊的信息

對比圖 4 與圖 6 所示的頁面不難發現,它們顯示的內容是一樣的。因此,無論是生成 HTML 頁面,還是直接啟動 HTTP 服務器,都能看到相同的文檔頁面。

pydoc查找模塊

此外,pydoc 還提供了一個 -k 選項,該選項用于查找模塊。該選項的語法格式如下:

python -m pydoc -k 被搜索模塊的部分內容

例如,在 fkmodule.py 所在目錄下運行如下命令:

python -m pydoc -k fk

可以看到如下輸出信息:

fkmodule

從上面的輸出信息可以看到,pydoc 找到了包含“fk”的 fkmodule。
< 上一頁Python文檔和測試 Python doctest下一頁 >

精美而實用的網站,提供C語言、C++、STL、Linux、Shell、Java、Go語言等教程,以及socket、GCC、vi、Swing、設計模式、JSP等專題。

Copyright ?2011-2018 biancheng.net, 陜ICP備15000209號

底部Logo