萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Python 內建文檔神器 pydoc 完整使用指南:從終端機到網頁文檔一鍵生成

Python 標準庫 pydoc 能從模組的 docstring 自動生成文檔,支援終端機文字、HTML 檔案、本地 HTTP 伺服器三種輸出模式,零配置、即拿即用,是中小專案文檔化的首選工具。

基本呼叫方式

平台指令範例
Windowspython -m pydoc <module>python -m pydoc math
Linux/Unixpydoc <module>pydoc os

常用參數速查

pydoc -h              # 顯示說明
pydoc -k keyword      # 全模組關鍵字搜尋
pydoc -p 1234         # 啟動 HTTP 伺服器於 localhost:1234
pydoc -w module       # 生成 module.html 於當前目錄

實戰演示

1. 啟動本地文檔伺服器

D:\> python -m pydoc -p 1234
pydoc server ready at https://localhost:1234/

瀏覽器即可檢索所有已安裝模組文檔,支援搜尋與超連結導航。

2. 關鍵字搜尋

$ pydoc -k xml.sax
xml.sax (package) - Simple API for XML (SAX) implementation for Python.
xml.sax.handler - core classes of SAX version 2.0
...

3. 生成 HTML 文檔

D:\LearnPython> python -m pydoc -w math math.html
wrote math.html

右上角顯示 (built-in) 表示內建模組。

4. 自訂模組文檔化

# my_doc.py
'''
Showoff features of Pydoc module
This is easy module to demonstrate docstrings
'''
__authors__ = 'Alice & Fred'
__version__ = 'version 1.10'

class MyClass:
    '''Demonstrate Class Docstrings'''
    def __init__(self, spam=1, eggs=2):
        '''Set default attribute values
        spam - a processed meat product
        eggs - a fine breakfast for lumberjacks'''
        self.spam = spam
        self.eggs = eggs

def square(x):
    '''Square of the param x'''
    return x * x
D:\LearnPython> python -m pydoc my_doc
# 終端機顯示結構化文檔

D:\LearnPython> python -m pydoc -w my_doc my_doc.html
wrote my_doc.html

優缺點評析

  • ✅ 零依賴、標準庫內建
  • ✅ 支援類別、函式、模組層級 docstring
  • ✅ 可生成可瀏覽的 HTML 與 HTTP 服務
  • ❌ 樣式固定,難以客製化主題
  • ❌ 大型專案建議改用 Sphinx、MkDocs 等專業工具
copyright © 萬盛學電腦網 all rights reserved