在開發工作中，我們經常需要分享或歸檔 Python 腳本文件。.py 文件雖然在編輯器中可讀性強，但直接發送給他人時，缺乏格式統一、排版美觀，且打印體驗不佳。尤其是在技術文檔、培訓資料或項目報告中，將代碼轉換為 PDF 不僅便於閲讀，也能保證跨平台展示效果一致。

Python 生態中有多種方式可以實現代碼轉 PDF，而 Free Spire.Doc for Python 提供了穩定、易用的方案。本文將介紹兩種常見的實現方法：普通文本方式和帶語法高亮的 HTML 插入方式，並詳細分析兩者的差異與使用場景。

1. 使用 Spire.Doc 將 Python 代碼按行寫入 PDF

最簡單的方法是將 .py 文件逐行讀取，並將每一行以固定字體插入到 PDF 中。這種方式適合不需要語法高亮，只希望保留原始代碼排版的場景。

from spire.doc import Document, FileFormat, BreakType, Color, LineSpacingRule, LineNumberingRestartMode

# 讀取 Python 文件
with open("Python.py", "r", encoding="utf-8") as f:
    python_code = f.read()

# 創建文檔對象
doc = Document()
section = doc.AddSection()
paragraph = section.AddParagraph()

# 逐行添加代碼
for line_number, line in enumerate(python_code.split("\n")):
    tr = paragraph.AppendText(line)
    tr.CharacterFormat.FontName = "Courier New"  # 設置等寬字體
    tr.CharacterFormat.FontSize = 10.5
    if line_number < len(python_code.split("\n")) - 1:
        paragraph.AppendBreak(BreakType.LineBreak)

# 可選格式設置
paragraph.Format.BackColor = Color.get_WhiteSmoke()  # 背景色
paragraph.Format.LineSpacingRule = LineSpacingRule.Multiple
paragraph.Format.LineSpacing = 14.0

# 行號設置
section.PageSetup.LineNumberingStartValue = 1
section.PageSetup.LineNumberingStep = 1
section.PageSetup.LineNumberingRestartMode = LineNumberingRestartMode.RestartPage
section.PageSetup.LineNumberingDistanceFromText = 12.0

# 保存為 PDF
doc.SaveToFile("output/Python-PDF.pdf", FileFormat.PDF)

轉換結果：

説明與優化點：

• 字體選擇：使用等寬字體（如 Courier New）保證代碼對齊整齊。
• 行間距：設置多倍行距可提高可讀性。
• 背景色與行號：輕微灰色背景搭配行號，更適合打印或閲讀。

這種方式的優勢在於實現簡單，代碼結構完全保留，兼容性高，但缺點是無法提供語法高亮效果，對於較長或複雜代碼可讀性稍差。

2. 使用 Pygments 生成帶語法高亮的 PDF

如果希望 PDF 中的代碼帶顏色區分關鍵字、註釋、字符串等，可以先使用 Pygments 將 Python 代碼轉換為 HTML，再通過 Spire.Doc 將 HTML 插入 PDF。

from spire.doc import Document, FileFormat
from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter

def py_to_inline_html(py_file_path):
    with open(py_file_path, "r", encoding="utf-8") as f:
        code = f.read()
    # 生成行內 HTML，帶行號
    formatter = HtmlFormatter(noclasses=True, linenostart=1, linenos='inline')
    return highlight(code, PythonLexer(), formatter)

html_result = py_to_inline_html("Python.py")

doc = Document()
section = doc.AddSection()
paragraph = section.AddParagraph()
paragraph.AppendHTML(html_result)

# 保存帶高亮的 PDF
doc.SaveToFile("output/Python-PDF-Highlighted.pdf", FileFormat.PDF)

轉換結果：

關鍵説明：

• HtmlFormatter(noclasses=True, linenos='inline')：生成內聯樣式 HTML，並帶行號。
• AppendHTML 方法可以直接將 HTML 內容插入到 PDF，保留語法高亮效果。
• 使用這種方法生成的 PDF 更美觀，適合演示文檔、教程或培訓資料。

3. 兩種方法的對比與使用建議

總結來看，如果對語法高亮要求不高，按行插入文本即可；如果希望 PDF 更美觀、可讀性高，HTML 高亮方式更合適。

4. 擴展説明

1. 合併重複操作：在按行插入的方式中，背景色、行距、字體等可封裝為函數，避免重複設置，提高代碼複用性。
2. 代碼排版與打印：PDF 是固定排版格式的文檔，將 Python 代碼導出後可確保不同環境中顯示一致，避免字體或縮進混亂。
3. 批量處理：可將以上方法封裝為函數，循環處理多個 .py 文件，實現批量生成 PDF，適合團隊協作或項目文檔歸檔。

總結

本文介紹了兩種將 Python 腳本轉換為 PDF 的方法：一種是按行插入文本，另一種是通過 HTML 生成語法高亮效果。前者簡單高效，適合快速歸檔；後者美觀專業，適合文檔和演示場景。通過掌握 Spire.Doc 的 AppendText 和 AppendHTML 方法，以及 Pygments 的 HTML 轉換能力，可以輕鬆生成結構清晰、可讀性強的 Python PDF 文檔。

無論是個人筆記整理、項目文檔歸檔，還是教學演示，這兩種方法都能滿足不同需求，提高代碼分享和管理的效率，同時保留排版美觀性。