# `pydoc` --- 文件產生器與線上幫助系統

原始碼：Lib/pydoc.py

`pydoc` 模組會自動從 Python 模組產生文件。文件可以以文字頁面的形式呈現在主控台上、提供給網頁瀏覽器，或儲存為 HTML 檔案。

對於模組、類別、函式和方法，所顯示的文件是從物件的說明字串（也就是物件的 `__doc__` 屬性）以及遞迴地從其可文件化成員的說明字串所取得。如果沒有說明字串，`pydoc` 會嘗試從原始碼檔案中，類別、函式或方法定義正上方的註解區塊，或從模組的頂部取得描述（參見 `inspect.getcomments()`）。

內建函式 `help()` 會在互動式直譯器中呼叫線上幫助系統，它會使用 `pydoc` 在主控台上以文字形式產生文件。同樣的文字文件也可以在 Python 直譯器外部檢視，方法是在作業系統的命令提示字元中，將 pydoc 當作腳本執行。例如，執行：

    python -m pydoc sys

在 shell 提示字元下，將會顯示 `sys` 模組的文件，其風格類似於 Unix man 命令所顯示的手冊頁面。pydoc 的引數可以是函式、模組或套件的名稱，或是一個指向模組中或套件中模組內的類別、方法或函式的點號參照 (dotted reference)。如果 pydoc 的引數看起來像一個路徑（也就是說，它包含你作業系統的路徑分隔符，例如 Unix 中的斜線），並且指向一個已存在的 Python 原始碼檔案，那麼就會為該檔案產生文件。

備註

為了找到物件及其文件，`pydoc` 會引入要文件化的模組。因此，任何在模組層級的程式碼都會在那個時候被執行。使用 `if __name__ == '__main__':` 的防護措施，可以確保程式碼只在檔案作為腳本被呼叫時執行，而不會在被引入時就執行。

當在主控台印出輸出內容時，pydoc 會嘗試將輸出內容做分頁以便於閱讀。如果 `MANPAGER` 或 `PAGER` 環境變數其中之一被設定，pydoc 將會使用其值作為分頁程式。當兩者都被設定時，會使用 `MANPAGER`。

在引數前指定一個 `-w` 旗標，將會使 HTML 文件被寫入目前目錄的一個檔案中，而不是在主控台上顯示文字。

在引數前指定一個 `-k` 旗標，將會搜尋所有可用模組的摘要行 (synopsis lines)，尋找作為引數給出的關鍵字，其方式同樣類似於 Unix 的 man 命令。一個模組的摘要行是其說明字串的第一行。

你也可以使用 pydoc 在本機上啟動一個 HTTP 伺服器，它會向來訪的網頁瀏覽器提供文件。python -m pydoc -p 1234 將會在 1234 埠啟動一個 HTTP 伺服器，讓你可以用你偏好的網頁瀏覽器在 `http://localhost:1234/` 瀏覽文件。指定 `0` 作為通訊埠編號將會選擇一個任意未使用的通訊埠。

python -m pydoc -n <hostname> 將會啟動伺服器並在給定的主機名稱上監聽。預設的主機名稱是 'localhost'，但如果你希望伺服器能被其他機器連線，你可能會想改變伺服器回應的主機名稱。在開發期間，如果你想在容器內執行 pydoc，這點特別有用。

python -m pydoc -b 將會啟動伺服器，並額外開啟一個網頁瀏覽器到模組索引頁面。每個提供的頁面頂部都有一個導覽列，你可以在那裡 Get（取得）個別項目的幫助、Search（搜尋）所有在其摘要行中包含關鍵字的模組，以及前往 Module index（模組索引）、Topics（主題）和 Keywords（關鍵字）頁面。

當 pydoc 產生文件時，它會使用目前的環境和路徑來定位模組。因此，呼叫 pydoc spam 所產生的文件，會完全對應到你啟動 Python 直譯器並輸入 `import spam` 時所取得的模組版本。

核心模組的文件被假定存放在 `https://docs.python.org/X.Y/library/`，其中 `X` 和 `Y` 是 Python 直譯器的主版本號和次版本號。這可以透過將 `PYTHONDOCS` 環境變數設定為不同的 URL 或包含函式庫參考手冊頁面的本機目錄來覆寫。

在 3.2 版的變更: 新增 `-b` 選項。

在 3.3 版的變更: 移除 `-g` 命令列選項。

在 3.4 版的變更: `pydoc` 現在使用 `inspect.signature()` 而不是 `inspect.getfullargspec()` 來從可呼叫物件中提取簽章資訊。

在 3.7 版的變更: 新增 `-n` 選項。