pydoc --- 文檔生成器和在線(xiàn)幫助系統?

源代碼: Lib/pydoc.py

pydoc 模塊會(huì )根據 Python 模塊來(lái)自動(dòng)生成文檔。 生成的文檔可在控制臺中顯示為文本頁(yè)面，提供給 Web 瀏覽器訪(fǎng)問(wèn)或者保存為 HTML 文件。

對于模塊、類(lèi)、函數和方法，顯示的文檔內容取自文檔字符串（即 __doc__ 屬性），并會(huì )遞歸地從其帶文檔的成員中獲取。 如果沒(méi)有文檔字符串，pydoc 會(huì )嘗試從類(lèi)、函數或方法定義上方，或是模塊頂部的注釋行段落獲取 (參見(jiàn) inspect.getcomments()).

內置函數 help() 會(huì )發(fā)起調用交互式解釋器的在線(xiàn)幫助系統，該系統使用 pydoc 在終端上生成文本形式的文檔內容。 同樣的文本文檔也可以在 Python 解釋器以外通過(guò)在操作系統的命令提示符下以腳本方式運行 pydoc 來(lái)查看。 例如，運行

pydoc sys

在終端提示符下將通過(guò) sys 模塊顯示文檔內容，其樣式類(lèi)似于 Unix man 命令所顯示的指南頁(yè)面。 pydoc 的參數可以為函數、模塊、包，或帶點(diǎn)號的對模塊中的類(lèi)、方法或函數以及包中的模塊的引用。 如果傳給 pydoc 的參數像是一個(gè)路徑（即包含所在操作系統的路徑分隔符，例如 Unix 的正斜杠），并且其指向一個(gè)現有的 Python 源文件，則會(huì )為該文件生成文檔內容。

當打印輸出到控制臺時(shí)，pydoc 會(huì )嘗試對輸出進(jìn)行分頁(yè)以方便閱讀。 如果設置了 PAGER 環(huán)境變量，pydoc 將使用該變量值作為分頁(yè)程序。

在參數前指定 -w 旗標將把 HTML 文檔寫(xiě)入到當前目錄下的一個(gè)文件中，而不是在控制臺中顯示文本。

在參數前指定 -k 旗標將在全部可用模塊的提要行中搜索參數所給定的關(guān)鍵字，具體方式同樣類(lèi)似于 Unix man 命令。 模塊的提要行就是其文檔字符串的第一行。

你還可以使用 pydoc 在本機上啟動(dòng)一個(gè) HTTP 服務(wù)器并向來(lái)訪(fǎng)的 Web 瀏覽器展示文檔。 pydoc -p 1234 將在 1234 端口上啟動(dòng) HTTP 服務(wù)器，允許在你使用 Web 瀏覽器通過(guò) http://localhost:1234/ 來(lái)瀏覽文檔內容。 指定 0 作為端口號將任意選擇一個(gè)未使用的端口。

pydoc -n <hostname> 將啟動(dòng)在給定主機名上執行監聽(tīng)的服務(wù)。 默認主機名為 'localhost' 但如果你希望能從其他機器搜索該服務(wù)器，你可能會(huì )想要改變服務(wù)器所響應的主機名。 在開(kāi)發(fā)階段此特性會(huì )特別有用，因為這樣你將能在一個(gè)容器中運行 pydoc。

pydoc -b 將啟動(dòng)服務(wù)并額外打開(kāi)一個(gè) Web 瀏覽器訪(fǎng)問(wèn)模塊索引頁(yè)。 所發(fā)布的每個(gè)頁(yè)面頂端都帶有導航欄，你可以點(diǎn)擊 Get 獲取特定條目的幫助，點(diǎn)擊 Search 在所有模塊的提要行中搜索特定關(guān)鍵詞，或是點(diǎn)擊 Module index, Topics 和 Keywords 前往相應的頁(yè)面。

當 pydoc 生成文檔內容時(shí)，它會(huì )使用當前環(huán)境和路徑來(lái)定位模塊。 因此，發(fā)起調用 pydoc spam 得到的文檔版本會(huì )與你啟動(dòng) Python 解釋器并輸入 import spam 時(shí)得到的模塊版本完全相同。

核心模塊的模塊文檔位置對應于 https://docs.python.org/X.Y/library/ 其中 X 和 Y 是 Python 解釋器的主要版本號和小版本號。 這可通過(guò)設置 PYTHONDOCS 環(huán)境變量來(lái)重載為指向不同的 URL 或包含 Library Reference Manual 頁(yè)面的本地目錄。