"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" 選項。
