使用 Sphinx 將 Laravel 文件轉成 epub

Laravel 官方文件的寫法若直接用 Sphinx 轉換成 EPUB 會遇到很多問題，如

1. ```shell tab=Linux 這種標籤效果，好像各轉換工具沒辦法直接處理好。
2. 文件中 Markdown 使用 <img> 引用外部圖片，需下載回來包在 epub。
3. 文件中 Markdown 使用 <img> 沒有正確的結束語法，因此無法通過 XHTML 驗證。
4. 程式碼區塊使用的語言不被認得，例如 blade , 這都要額外設定修正。

為了解決上述問題，這邊提供了修正程式來解決這問題，且將轉換過程需要的設定都撰寫成樣板，方便日後使用。

專案目錄結構介紹

• bin/preprocess_docs.py : 可用來修復 Markdown 內的各種問題，包含自動下載圖片存放於本地端。
• bin/gen_index.py : 用於動態產生目錄(TOC)檔案的程式，主要依據 documention.md 內容產生，轉換後會放至 workspace/preprocess/{version}。
• bin/build.sh : 簡單的 bash 以執行 preprocess_docs.py 與 sphinx-build 建立 epub 檔案。
• template : 現成的樣板。
• sphinx_extension : 目前只有一個 torchlight.py 主要用於增強 Pygments 產生的結構。
• pygments_styles : 目前只有一個 grayscale.py，主要用於產生適合 黑白 E-INK 螢幕的 css。

環境需求

如果系統能跑 docker，可以跳過本段說明，使用 docker 跑比較簡單，若沒辦法跑 docker , 需要準備好以下必備軟體

• Linux : 目前提供的 shell , py 都只有在 Linux 測過，也許 Mac 也行吧。
• Python3
• Sphinx
• requirements.txt 內有 PIP 所需套件都要安裝。

以下簡單介紹 Sphinx 的安裝方式 , 假設你已經 clone 本專案了，就直接於本專案的根目錄下操作即可

python3 -m venv .venv
chmod +x .venv/bin/activate
.venv/bin/activate
source .venv/bin/activate
pip install sphinx sphinx-rtd-theme recommonmark

這樣就會於本專案建立 venv 的虛擬環境，所安裝的軟體只能在專案內使用。不會影響到全域 Python。

使用現成的樣板以 Sphinx 轉換為 EPUB

1. 將 template 整份複製為 workspace

   cp -Rf template workspace

2. 將 Laravel 文件以 git clone 至 workspace 的 source。

   cd workspace
   git clone https://github.com/laradoc-trans-lab/laravel_docs-zh_TW.git ./source
   cd ..

3. 如有需要可以修改 workspace/conf.py，設定檔都有中文註解了。

注意，workspace/source 一定要是一個 git 倉庫，且有各版本的分支。

接下來就可以進行轉換了 , 假設要轉換 12.x 的版本

若環境有 docker 執行以下命令:

docker compose run -u $UID:$GID --rm builder 12.x

環境沒有 docker 執行以下命令:

bin/build.sh 12.x

就這麼簡單，所有 Markdwon 修正與轉換為 epub 都會依照現有的目錄結構自動完成，轉換過程會有一些紅字 WARNING 不用理會，如果轉換成功，應該可以看到幾個變化

• workspace/source: 這是原始文件的 git repo，此時分支應該是切換到建置 epub 時的分支。
• workspace/preprocess: 預處理的檔案，詳情可以參考 bin/build.sh 裡面做了甚麼，sphinx-build 主要是以此目錄當作文件來源。
• workspace/build : 輸出為 epub 時，會將所有檔案儲存於此。

Author

Pigo Chu pigochu@gmail.com

Lincense

本專案提供的工具與教學步驟使用 MIT 授權。