如何自行建構 Python 的官方文件,並將其內文字體大小調大

紀錄如何於 Docker 容器環境自行建構 Python 的官方文件以滿足文字大小客製需求

Image Not Showing Possible Reasons
  • The image was uploaded to a note which you don't have access to
  • The note which the image was originally uploaded to has been deleted
Learn More →

問題(Problem)

  • Python 官方文件的 PDF 版本在 reMarkable 電子紙平板電腦上呈現出來的內文字元大小偏小
  • reMarkable 的 EPUB 支援有限,無法正常開啟/呈現部份電子書

解決方案(Solution)

手動建構一個字型與版型客製過的 Python 說明文件,改進 Python 文件在 reMarkable 電子紙平板電腦上的閱覽體驗

前備條件(Prerequisites)

以下說明完成本流程所需的前備條件:

  • 您須已安裝近期版本的 Docker Engine 容器執行環境container runtime以創建建構文件用的作業系統容器
  • 您須可以訪問網際網路internet以獲取建構文件所需要的軟體
  • 您須有基本的 GNU+Linux 作業系統操作經驗,包含但不限於:
    • 絕對路徑absolute path相對路徑relative path的理解
    • GNU Bash 殼層shell操作界面的使用

重現環境(Reproducing environment)

以下說明確認可以重現本教學內容的具體環境細節:

主端(host)作業系統

Ubuntu 23.10

Docker Engine

24.0.5

建構文件所使用的 Python 軟體來源碼

3.12.2

取得 Python 來源程式碼封存檔(archive)

  1. Python 官方網站軟體下載頁選擇要下載的 Python 版本:

    Image Not Showing Possible Reasons
    • The image was uploaded to a note which you don't have access to
    • The note which the image was originally uploaded to has been deleted
    Learn More →

  2. 然後於頁面下方的 Files 區塊選擇任一作業系統欄位為「Source release」的軟體來源碼封存檔下載連結下載 Python 的軟體來源碼封存檔:

    Image Not Showing Possible Reasons
    • The image was uploaded to a note which you don't have access to
    • The note which the image was originally uploaded to has been deleted
    Learn More →

    於本教學中我們選擇 XZ 壓縮方式的軟體來源碼封存檔進行下載,因為 XZ 壓縮演算法的壓縮率較好故下載檔案的所需時間較少。

解開(extract) Python 來源程式碼封存檔

使用偏好的封存檔操作應用軟體將下載的軟體來源碼封存檔解開

備註: 您另可使用 GNU Tar 這個命令列界面command-line interface的封存檔操作工具進行封存檔的解開操作:

cd /path/to/extraction/destination/dir
tar_opts=(
    --extract
    --file=/path/to/python-3.12.2.tar.xz
)
tar "${tar_opts[@]}"

附註:

  • array=(...) 為 Bash 的索引式陣列indexed array語法,如上範例命令為例使用此語法可以以 Bash 註解的形式為命令參數新增說明文字
  • "${array[@]}" 為 Bash 陣列的其中一種參數展開parameter expansion語法,會將陣列中的元素以空白字元為分隔插入於展開處,您可以在展開命令前面加上 echo 命令(如 echo "${array[@]}")以預覽展開結果

創建並啟動一建構文件用的 Docker 容器(container)

為了確保重現環境的一致性consistency,我們使用 Docker 創建一個作業系統容器operating system container並在其內進行文件建構作業

  1. 啟動一文字終端機(text terminal)模擬器應用軟體

  2. 以 root 身份 執行下列命令創建並啟動一拋棄式(ephemeral)的 Ubuntu 22.04 容器:

    ​​​​python_source_dir=/path/to/Python-X.Y.Z
    ​​​​docker_run_opts=(
    ​​​​    # 離開容器的作業階段時自動摧毀容器,節省磁碟空間使用
    ​​​​    --rm
    
    ​​​​    # 啟用標準輸入裝置(stdin)支援(使 bash shell 得以互動式模式運行)
    ​​​​    --interactive
    
    ​​​​    # 啟用偽 Teletype(TTY) 終端機模擬功能(使 bash shell 得以互動式模式正常運行)
    ​​​​    --tty
    ​​​​    
    ​​​​    # 創建一 bind-mount 式儲存空間(volume),將主端的 Python 軟體來源碼封存檔解開目錄
    ​​​​    # 掛載到容器中的 /project 目錄下
    ​​​​    --mount "type=bind,source=${python_source_dir},destination=/project"
    ​​​​)
    ​​​​docker run "${docker_run_opts[@]}" ubuntu:22.04
    

    附註:

    • 如您的使用者為 docker 使用者群組的成員則可以以一般使用者身份運行前述 docker run 命令(允許使用者直接訪問 Docker 服務有潛在的安全風險,應僅開放給完全信任的使用者使用)
    • 如您位於僅能透過一 HTTP(S) 正向代理服務器才能連到網際網路的網路環境(如企業內部網路或是使用 TetherFi 應用分享手機的行動網路給電腦),您可以在執行 docker run 命令前額外執行下列命令將本地的 HTTP(S) 正向代理服務設定(須已設定相關環境變數)繼承給 Docker 容器使用:
      • docker_run_opts+=(--env http_proxy)
      • docker_run_opts+=(--env https_proxy)
      • docker_run_opts+=(--env no_proxy)

切換作業目錄(working directory)至 Python 來源程式碼目錄樹中的說明文件目錄

執行下列命令切換作業目錄至 Python 來源程式碼目錄樹中的說明文件目錄

cd /project/Doc

改用本地的 Ubuntu 軟體庫鏡像服務(software repository mirror)

操作方式參閱《如何改用本地的軟體庫鏡像服務 | 大家的 Linux 團圓飯》教學文件

更新軟體包管理系統(software package management system)的本地快取(cache)資料

操作方式參閱《如何更新軟體包管理系統的本地快取資料 | 大家的 Linux 團圓飯》教學文件

安裝創建 Python 虛擬環境(virtual environment)依賴軟體(software dependencies)

因為 Python 官方文件的 README 說明文件(Python-X.Y.Z/Doc/README) 建議使用 Python 虛擬環境進行文件建構,所以我們要先安裝其依賴軟體:

  • GNU Make 軟體建構自動化build automation工具
    用於載入並執行建構 Python 說明文件用的 Makefile
  • Python 第三版執行環境
    提供 Python 虛擬環境的執行環境
  • Python venv 模組
    提供虛擬環境建構支援

於 Ubuntu 22.04 作業系統中可以 以 root 身份 執行下列命令進行安裝:

pyvenv_dependency_pkgs=(
    make
    python3
    python3-venv
)
apt install "${pyvenv_dependency_pkgs[@]}"

創建建構 Python 說明文件用的 Python 虛擬環境

執行下列命令以創建建構 Python 說明文件用的 Python 虛擬環境:

make venv

套用 Sphinx 配置修正:改用 US-Letter 紙張大小

Python 官方文件的 PDF 版本預設使用 A4 的紙張大小進行輸出,因 reMarkable 電子紙平板的螢幕解析度為 1872 x 1404,為 4:3 長寬比的螢幕,改用較接近 4:3 長寬比的 US-Letter 紙張大小較能夠避免頁面縮放貼合螢幕邊緣造成文字大小變小

編輯 conf.py Sphinx 配置檔,於「Options for LaTeX output」區域 latex_elements 字典的 papersize 鍵的值自 a4 修改為 letter

套用 Sphinx 配置修正:增加內文字體大小

編輯 conf.py Sphinx 配置檔,於「Options for LaTeX output」區域 latex_elements 字典的 pointsize 鍵的值自 10pt 修改為 12pt

附註: 這個設定似乎只支援以下三個數值:

  • 10pt
  • 11pt
  • 12pt

建構 LaTeX 版本文件

執行下列命令建構 LaTeX 格式的文件:

make latex

安裝建構 PDF 文件的依賴軟體

pdf_build_dependency_pkgs=(
    # 提供 GNU Freefont 這個建構 PDF 文件需要的字型
    fonts-freefont-otf
    
    latexmk
    texlive-xetex
    texlive-fonts-recommended
    xindy
)
apt_install_opts=(
    # 不要安裝推薦安裝軟體包,避免非必要地下載太多實際上沒用到的軟體
    --no-install-recommends
)
apt install "${apt_install_opts[@]}" "${pdf_build_dependency_pkgs[@]}"

自 LaTeX 版本文件建構 PDF 版本文件

切換作業目錄至 LaTeX 格式文件輸出目錄:

cd build/latex

然後執行下列命令建構 PDF 版本文件:

make all-pdf

順利的話建構好的 PDF 版本文件會存放於 build/latex 目錄中

參考資料(References)

以下列舉撰寫文文件期間所參考的第三方資源: