pydoc
--- 文檔生成器和在線幫助系統(tǒng)?
源代碼: Lib/pydoc.py
pydoc
模塊會根據(jù) Python 模塊來自動生成文檔。 生成的文檔可在控制臺中顯示為文本頁面,提供給 Web 瀏覽器訪問或者保存為 HTML 文件。
對于模塊、類、函數(shù)和方法,顯示的文檔內(nèi)容取自文檔字符串(即 __doc__
屬性),并會遞歸地從其帶文檔的成員中獲取。 如果沒有文檔字符串,pydoc
會嘗試從類、函數(shù)或方法定義上方,或是模塊頂部的注釋行段落獲取 (參見 inspect.getcomments()
).
內(nèi)置函數(shù) help()
會發(fā)起調(diào)用交互式解釋器的在線幫助系統(tǒng),該系統(tǒng)使用 pydoc
在終端上生成文本形式的文檔內(nèi)容。 同樣的文本文檔也可以在 Python 解釋器以外通過在操作系統(tǒng)的命令提示符下以腳本方式運行 pydoc 來查看。 例如,運行
pydoc sys
在終端提示符下將通過 sys
模塊顯示文檔內(nèi)容,其樣式類似于 Unix man 命令所顯示的指南頁面。 pydoc 的參數(shù)可以為函數(shù)、模塊、包,或帶點號的對模塊中的類、方法或函數(shù)以及包中的模塊的引用。 如果傳給 pydoc 的參數(shù)像是一個路徑(即包含所在操作系統(tǒng)的路徑分隔符,例如 Unix 的正斜杠),并且其指向一個現(xiàn)有的 Python 源文件,則會為該文件生成文檔內(nèi)容。
備注
為了找到對象及其文檔內(nèi)容,pydoc
會導(dǎo)入文檔所在的模塊。 因此,任何模塊層級的代碼都將被執(zhí)行。 請使用 if __name__ == '__main__':
語句來確保一個文件的特定代碼僅在作為腳本被發(fā)起調(diào)用時執(zhí)行而不是在被導(dǎo)入時執(zhí)行。
當打印輸出到控制臺時,pydoc 會嘗試對輸出進行分頁以方便閱讀。 如果設(shè)置了 PAGER
環(huán)境變量,pydoc 將使用該變量值作為分頁程序。
在參數(shù)前指定 -w
旗標將把 HTML 文檔寫入到當前目錄下的一個文件中,而不是在控制臺中顯示文本。
在參數(shù)前指定 -k
旗標將在全部可用模塊的提要行中搜索參數(shù)所給定的關(guān)鍵字,具體方式同樣類似于 Unix man 命令。 模塊的提要行就是其文檔字符串的第一行。
你還可以使用 pydoc 在本機上啟動一個 HTTP 服務(wù)器并向來訪的 Web 瀏覽器展示文檔。 pydoc -p 1234 將在 1234 端口上啟動 HTTP 服務(wù)器,允許在你使用 Web 瀏覽器通過 http://localhost:1234/
來瀏覽文檔內(nèi)容。 指定 0
作為端口號將任意選擇一個未使用的端口。
pydoc -n <hostname> 將啟動在給定主機名上執(zhí)行監(jiān)聽的服務(wù)。 默認主機名為 'localhost' 但如果你希望能從其他機器搜索該服務(wù)器,你可能會想要改變服務(wù)器所響應(yīng)的主機名。 在開發(fā)階段此特性會特別有用,因為這樣你將能在一個容器中運行 pydoc。
pydoc -b 將啟動服務(wù)并額外打開一個 Web 瀏覽器訪問模塊索引頁。 所發(fā)布的每個頁面頂端都帶有導(dǎo)航欄,你可以點擊 Get 獲取特定條目的幫助,點擊 Search 在所有模塊的提要行中搜索特定關(guān)鍵詞,或是點擊 Module index, Topics 和 Keywords 前往相應(yīng)的頁面。
當 pydoc 生成文檔內(nèi)容時,它會使用當前環(huán)境和路徑來定位模塊。 因此,發(fā)起調(diào)用 pydoc spam 得到的文檔版本會與你啟動 Python 解釋器并輸入 import spam
時得到的模塊版本完全相同。
核心模塊的模塊文檔位置對應(yīng)于 https://docs.python.org/X.Y/library/
其中 X
和 Y
是 Python 解釋器的主要版本號和小版本號。 這可通過設(shè)置 PYTHONDOCS
環(huán)境變量來重載為指向不同的 URL 或包含 Library Reference Manual 頁面的本地目錄。
在 3.2 版更改: 添加 -b
選項。
在 3.3 版更改: 命令行選項 -g
已經(jīng)移除。
在 3.4 版更改: pydoc
現(xiàn)在會使用 inspect.signature()
而非 inspect.getfullargspec()
來從可調(diào)用對象中提取簽名信息。
在 3.7 版更改: 添加 -n
選項。