Jupyter Book

# 1 Jupyter Book とは

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/414636/627df84e-f81e-a83e-d901-ff66280ef8a6.png)

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

https://jupyterbook.org/en/stable/intro.html

https://www.sphinx-doc.org/en/master/

https://myst-parser.readthedocs.io/en/latest/index.html

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

![jb-scipy.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/414636/db50e35f-96bb-ecdb-e978-6b44fccab034.png)

基本的なマークダウンと同様に数式やソースコードが書けるのはもちろん、豊富な[ノート記法](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html#admonition-types)（qiita でいう`:::note ~ :::`、admonition や directive と呼ばれます）や[ドロップダウン](https://jupyterbook.org/en/stable/content/components.html#the-dropdown-directive)、[タブコンテンツ](https://jupyterbook.org/en/stable/content/components.html#tab-content)、[相互参照](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html)、などを使うことができます。詳しくは、[こちら](https://jupyterbook.org/en/stable/content/myst.html)を参照ください。

# 2 数式

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

https://docs.mathjax.org/en/v3.2-latest/input/tex/extensions/index.html

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

```latex
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]"]
```

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

[このページに](https://kkensuke.github.io/myjb-ja/pages/latex/basics.html#physics)、`physics` package の例を挙げておいたのでどのようなコマンドが使えるのか見てください。

![physics.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/414636/748e265a-9977-e4c8-28b6-d2f1f073d6ea.png)

# 3 Jupyter Book の作成

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


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

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

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

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

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


## 3.2 jupyter-book をインストールする
```zsh
(venv)$ pip install -U jupyter-book
```

## 3.3 Jupyter Book の骨組みを作る

以下のコマンドで、Jupyter Book の骨組みを作成します。この時、`_config.yml`、`_toc.tml`、説明用の初期ファイルなどがいくつか生成されます。
```zsh
(venv)$ jb create test-book
(venv)$ cd test-book
(venv)$ jb build .
```


```zsh
~/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` が出力されるので、それをブラウザに貼り付けて、確認してみてください。

:::note
jb は jupyter-book の略です。
:::

![jupyter-book.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/414636/a2c15ffc-4f6e-363d-4363-925d44178421.png)

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

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

リポジトリを作成したら、`ghp-import` という Python ライブラリをインストールします。
```zsh
(venv)$ pip install ghp-import
```

あとは、次のコマンドを実行すれば、公開の準備は終わりです。
```zsh
(venv)$ ghp-import -n -p -f _build/html
```

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

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

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

```zsh
(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
```


# 4 その他

## 4.1 目次からブックファイルを作成する

`_toc.yml` ファイルを使用して、ブックの骨組みを自動的に作成することができます。これは、1つの構造から空のファイルを素早く生成し、その後自分で内容を追加したい場合に便利です。

```sh
jupyter-book toc to-project path/to/_toc.yml
```

## 4.2 テーマの変更

[https://github.com/executablebooks/jupyter-book/issues/718](https://github.com/executablebooks/jupyter-book/issues/718)



# 5 終わり

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

https://jupyterbook.org/en/stable/intro.html

https://myst-parser.readthedocs.io/en/latest/index.html