將 Jupyter Notebook 整理成一本書

從學期初修 Python 就一直在吃老本，直到最近學到物件導向才開始認真思索寫筆記這件事。就寫筆記而言，我最熟悉的 工具 當然是 R Markdown，而 RStudio 目前 對 Python 也有不錯的支援 。但我平常把 JupyterLab 當成 Python 的 IDE 在使用，自然比較習慣這個環境，因此就決定使用 Jupyter Notebook 來寫筆記。我第一個想到的問題就是：R Markdown 的世界裡有 bookdown 將多個 .Rmd 變成一本書 (網頁)，但 Jupyter Notebook 似乎沒有這麼方便的工具。 我錯了 。好概念傳播的很快，受到 bookdown 的啟發，Jupyter 的世界裡也出現了一套類似的工具 — Jupyter Book 。

What is Jupyter Book?

其實 Jupyter Book 的概念非常簡單：

1. 將 Jupyter Notebook ( .ipynb ) 轉換成 markdown ( .md )
2. 使用 Jekyll (靜態網頁產生器) 生成網頁

但它真正厲害的地方在於它的靜態網頁模板 ( 範例 )：

1. 版面風格與 Jupyter Notebook 類似
2. 網頁模板添加許多功能
   • .ipynb 下載連結
   • binder 連結
   • 直接執行程式碼 (byThebe Lab)

Jupyter Book 的 Jekyll 模板

Jupyter Book 提供了相當清楚易懂的 說明文件 。唯一需要注意的是，Jupyter Book 必須使用 Jekyll 才能在個人電腦上預覽網頁，而安裝 Jekyll 是非常麻煩的事 (尤其在 Windows 上)。為解決這麻煩，Jupyter Book 很細心的提供了 以 docker 使用 Jekyll 的方式 ，減少安裝 Jekyll 的麻煩 (但學習使用 docker 又是另一個麻煩事)。如果對於 Jekyll 運作了然於心，其實可以不用在個人電腦上安裝 Jekyll 預覽網頁，直接將生成的檔案丟到 GitHub 上讓 GitHub Pages 生成網頁。

但對多數人最頭痛的應該是 Jekyll 模板的結構，這邊提供快速上手的說明 (換言之，在不懂 Jekyll 下使用 Jupyter Book 的模板)。

使用 Jupter Book

1. 安裝

   pip install jupyter-book

2. 匯入模板

   jupyter-book create mybookname

   這個指令會匯入 Jupyter Book 的 Jekyll 模板 (簡化)：

   mybookname/
    ├── _config.yml
    ├── content
    │   ├── images
    │   │   └── logo
    │   │       └── favicon.ico
    │   └── notebook.ipynb
    └── _data
        └── toc.yml

   在這模板裡面，

   • content/

     存放 Jupyter Notebook 的地方，可依照自己喜好使用任意檔案結構 (e.g. content/01/ 裡面放多個 notebook，如 content/01/intro.ipynb , content/01/hello-world.ipynb ；或是直接將 notebook 丟在 content/ 之下)。

   • _data/toc.yml

     content/ 中的檔案結構可有很大彈性，因為網頁的目錄 (左欄) 連結是在 _data/toc.yml 中 手動設定 的。例如，要將 content/01/intro.ipynb 生成之網頁的連結放在目錄上 ，得在 _data/toc.yml 設定：

     - title: Introduction
       url: /01/intro
       not_numbered: false
       expand_sections: false

   • _config.yml

     這裡是設定 Jekyll 網頁的一些資訊，例如網站名稱和作者等。特別需要注意的是 baseurl 和 url 這兩個項目。如果你的網頁是透過 GitHub Pages 產生的 (假設這份 Jekyll 模板上傳到 GitHub 的 mybookname repo)，那 baseurl 就會是 /mybookname ：

     baseurl: /mybookname
     url: https://<user>.github.io

3. 輸出 (不需 Jekyll)：將 Working directory 設成 mybookname/ ，執行下方指令

   python scripts/clean.py  # 清理之前產生的檔案
   jupyter-book build ./    # 從 `contents/` 產生 Jekyll 能處理的檔案

4. 上傳至 GitHub (記得到 Repo 的 Settings 裡設定，讓 GitHub Pages 使用 master branch 生成網頁)

這樣就大功告成了！

My Python Note

liao961120/pynote 是我透過 Jupyter Book 設置的 Python 筆記 ，與上面介紹不同的是，我使用的是 netlify 而非 GitHub Pages；另外，我也透過 Travis-CI 幫我執行 python scripts/clean.py 與 jupyter-book build ./ ，所以就不用在每次修改筆記後，還得在電腦上跑這些指令。