1 Jupyter Book とは

Jupyter Book とは、さまざまな形式のドキュメント（HTML, PDF, ePUB など）を作成する Sphinx というツールと、MyST Markdown というサイエンスのドキュメントに適したマークダウンを融合させたツールです。一つのサイトページは一つの markdown ファイルを元に作られ、それらを _toc.yml ファイルにまとめて、Jupyter Book を構成します。

markdown だけでなく ipynb も一つのページとして使うことが可能で、Jupyter Book の作成時に ipynb を実行し結果も挿入することができます。(さらに、ipynb であれば、_config.yml で Google colaboratory を有効にすることによって、Jupyter Book の同じページをすぐに Google colaboratory を開いて実行することが可能です。)

基本的なマークダウンと同様に数式やソースコードが書けるのはもちろん、豊富なノート記法（qiita でいう:::note ~ :::、admonition や directive と呼ばれます）やドロップダウン、タブコンテンツ、相互参照、などを使うことができます。詳しくは、こちらを参照ください。

2 数式

Jupyter Book では、Latex がとても扱いやすいです。というのも、Sphinx の設定で MathJax3 を使うことができ、さまざまな Latex package をロードしたり、マクロを設定することができます。

例えば、physics package であれば、_config.yml に以下を追加することで使用可能になります。

sphinx:
  config:
    mathjax_path            : https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
    mathjax3_config:
      loader:
        load                : ['[tex]/physics']
      tex:
        packages            : { '[+]': ['physics'] }
        macros:
          "N": "\\mathbb{N}"
          "floor": ["\\lfloor#1\\rfloor", 1]
          "bmat" : ["\\left[\\begin{array}"]
          "emat" : ["\\end{array}\\right]"]

デフォルトでは、現在 MathJax バージョン 2 が使用されています。数式を頻繁に使用する場合は、バージョン 3 を使用してみてください。ロード速度が 60〜80% 倍向上すると言われています。

このページに、physics package の例を挙げておいたのでどのようなコマンドが使えるのか見てください。

3 Jupyter Book の作成

Jupyter Book の基本的な構成要素は、プロジェクトの初期化によって簡単に作ることができ、GitHub pages を使って簡単に公開もできます。

3.1 ディレクトリを作成する

Jupyter Book をゼロから作成してみましょう。まず、以下のディレクトリ構造を作成し、venv（仮想環境）をアクティベートします。

./jupyter-book
	└── test-book
	    ├── venv

$ mkdir -p ./jupyter-book/test-book
$ cd ./jupyter-book/test-book

$ python3 -m venv venv
$ source venv/bin/activate

3.2 jupyter-book をインストールする

(venv)$ pip install -U jupyter-book

3.3 Jupyter Book の骨組みを作る

以下のコマンドで、Jupyter Book の骨組みを作成します。この時、_config.yml、_toc.tml、説明用の初期ファイルなどがいくつか生成されます。

(venv)$ jb create test-book
(venv)$ cd test-book
(venv)$ jb build .

~/jupyter-book
	└── test-book
	    ├── venv
	    └── test-book
                ├── _condig.yml
                ├── _toc.yml
                ├── ...

無事、ビルドが完了すると、terminal に次のような HTML のファイル URL: file:///Users/<Username>/path/to/jupyterbook/test-book/test-book/_build/html/index.html が出力されるので、それをブラウザに貼り付けて、確認してみてください。

jb は jupyter-book の略です。

3.4 公開する

作成した Jupyter Book を公開するために、まず Github で test-book 専用のリポジトリをご自身で作成してください。

~/jupyter-book
	└── test-book
	    ├── venv
	    └── test-book
                ├── _condig.yml
                ├── _toc.yml
                ├── ...
                └── .git

リポジトリを作成したら、ghp-import という Python ライブラリをインストールします。

(venv)$ pip install ghp-import

あとは、次のコマンドを実行すれば、公開の準備は終わりです。

(venv)$ ghp-import -n -p -f _build/html

公開されたウェブサイトは https://<Username>.github.io/test-book/intro.html で確認できます。

サイトが公開されるまでに数分かかる場合があります。

3.5 更新する

ソースコードを変更した後、以下のコマンドでウェブサイトを更新できます。

(venv)$ jb build --all test-book/

(venv)$ git add .
(venv)$ git commit -m "comment"
(venv)$ git push origin main

(venv)$ ghp-import -n -p -f _build/html

5 その他

5.1

4 終わり

あとは、ドキュメントを参考にして、ご自分で色々な機能を試してみてください。