紀錄如何於 Docker 容器環境自行建構 Python 的官方文件以滿足文字大小客製需求
手動建構一個字型與版型客製過的 Python 說明文件,改進 Python 文件在 reMarkable 電子紙平板電腦上的閱覽體驗
以下說明完成本流程所需的前備條件:
以下說明確認可以重現本教學內容的具體環境細節:
Ubuntu 23.10
24.0.5
3.12.2
至 Python 官方網站軟體下載頁選擇要下載的 Python 版本:
然後於頁面下方的 Files 區塊選擇任一作業系統欄位為「Source release」的軟體來源碼封存檔下載連結下載 Python 的軟體來源碼封存檔:
於本教學中我們選擇 XZ 壓縮方式的軟體來源碼封存檔進行下載,因為 XZ 壓縮演算法的壓縮率較好故下載檔案的所需時間較少。
使用偏好的封存檔操作應用軟體將下載的軟體來源碼封存檔解開
備註: 您另可使用 GNU Tar 這個命令列界面的封存檔操作工具進行封存檔的解開操作:
cd /path/to/extraction/destination/dir
tar_opts=(
--extract
--file=/path/to/python-3.12.2.tar.xz
)
tar "${tar_opts[@]}"
附註:
array=(...)
為 Bash 的索引式陣列語法,如上範例命令為例使用此語法可以以 Bash 註解的形式為命令參數新增說明文字"${array[@]}"
為 Bash 陣列的其中一種參數展開語法,會將陣列中的元素以空白字元為分隔插入於展開處,您可以在展開命令前面加上 echo 命令(如 echo "${array[@]}"
)以預覽展開結果為了確保重現環境的一致性,我們使用 Docker 創建一個作業系統容器並在其內進行文件建構作業
以 root 身份 執行下列命令創建並啟動一拋棄式的 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 服務有潛在的安全風險,應僅開放給完全信任的使用者使用)docker run
命令前額外執行下列命令將本地的 HTTP(S) 正向代理服務設定(須已設定相關環境變數)繼承給 Docker 容器使用:
docker_run_opts+=(--env http_proxy)
docker_run_opts+=(--env https_proxy)
docker_run_opts+=(--env no_proxy)
執行下列命令切換作業目錄至 Python 來源程式碼目錄樹中的說明文件目錄
cd /project/Doc
操作方式參閱《如何改用本地的軟體庫鏡像服務 | 大家的 Linux 團圓飯》教學文件
操作方式參閱《如何更新軟體包管理系統的本地快取資料 | 大家的 Linux 團圓飯》教學文件
因為 Python 官方文件的 README 說明文件(Python-X.Y.Z/Doc/README) 建議使用 Python 虛擬環境進行文件建構,所以我們要先安裝其依賴軟體:
venv
模組於 Ubuntu 22.04 作業系統中可以 以 root 身份 執行下列命令進行安裝:
pyvenv_dependency_pkgs=(
make
python3
python3-venv
)
apt install "${pyvenv_dependency_pkgs[@]}"
執行下列命令以創建建構 Python 說明文件用的 Python 虛擬環境:
make venv
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
編輯 conf.py Sphinx 配置檔,於「Options for LaTeX output」區域 latex_elements
字典的 pointsize
鍵的值自 10pt
修改為 12pt
附註: 這個設定似乎只支援以下三個數值:
執行下列命令建構 LaTeX 格式的文件:
make latex
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 格式文件輸出目錄:
cd build/latex
然後執行下列命令建構 PDF 版本文件:
make all-pdf
順利的話建構好的 PDF 版本文件會存放於 build/latex 目錄中
以下列舉撰寫文文件期間所參考的第三方資源:
docker run
命令的 --volume
參數值的格式與用法pzdr
- TeX - LaTeX Stack Exchange