Jupyter Notebook(.ipynb)から出版品質の本やドキュメントを作成できる「Jupyter Book」の使い方

Jupyter Bookとは？

タイトルの通り、Jupyter Notebookファイル(.ipynb)やMarkdownファイル(.md)から、美しい出版品質の本やドキュメント(HTMLやPDFなど)を作成できるのが「Jupyter Book」です。URL先の公式リファレンスも、「Jupyter Book」を使って作成されています。他にも、東京大学素粒子物理国際研究センター（ICEPP）の、量子コンピューティングを手を動かして学びたい人向けの入門教材、「量子コンピューティング・ワークブック」もJupyterBookが使用されているようです。

名前がJupyter Notebookと似ていますが別のもので、「Project Jupyter」や「The Executable Book Project」のプロジェクトの1つです。Read the DocsのPython版とも解釈できます。自分が探した限りでは日本語のリファレンスがなかったので、Jupyter Bookについて簡単な紹介をしていこうと思います。執筆時点でのバージョンは0.9です。

インストール方法

pipを使って簡単にインストールすることができます。自分はpipとJupyter Lab環境でのインストールとなります。Jupyter Labのインストール方法はこちらの記事がおすすめです。

pipコマンドでインストールします。

% python3 -m pip install jupyter-book

Ubuntuでインストールを試したところ、/home/ユーザ名/.local/binへPATHを通す必要がありました。~/.bashrcなどに以下を追加してください。

~/.bashrc

export PATH="$PATH:/home/$(whoami)/.local/bin"

基本的なコマンド

インストール後、適当なディレクトリに移動してJupyter Bookプロジェクトを作成してみましょう。Jupyter Bookは、jupyter-bookまたはjbコマンドを使用します。どちらも違いはありませんので、以降は短いjbを使用します。

jb create

jb createで「test_book」という名前のJupyter Bookプロジェクトを作成します。プロジェクト名は変更して構いません。ここでは使用していませんが、createでは--cookiecutterオプションを付加することもできます。

% jb create test_book

test_book/にテンプレートのJupyter Bookが作成されました。

jb build

jb buildでJupyter Bookをビルドすることができます。

% cd test_book
% jb build .

ログが表示された後、ビルドが完了すると、以下のように表示されます。

test_book/_build/htmlにHTMLファイルが作成されています。Chromeなどのブラウザで表示させてみましょう。ブラウザにHTMLファイルのパスを入れると、次のように表示されるはずです。簡単にドキュメントを作成することができました。

公式デモブック

公式デモブックも用意されています。ビルド時にエラーが発生することがあるので、ビルド時の実行をしないオプションを個人的に推奨します。

% git clone https://github.com/executablebooks/quantecon-mini-example
% cd quantecon-mini-example/mini_book
% cat _config.yml

ここで_config.ymlのexecute_notebooksを"off"に書き換えます。

ビルドしてブラウザで表示させてみましょう。

% jb build .
% open /Applications/Google\ Chrome.app _build/html/index.html

PDFを作成する

HTMLと同様に、PDFの作成も簡単にすることができます。2通りの方法があり、少し違いがあります。

① ブラウザから作成する方法

ブラウザでHTMLを表示すると、右上にダウンロードボタンがあります。クリックすると、ダウンロードする形式を指定できます。.pdfをクリックするとPDFファイルを保存することができます。これで完了です。

② ビルドして作成する方法

こちらの方法にはpyppeteerが必要なので、インストールします。

% pip install pyppeteer

Jupyter Bookでは、1ページ単位でビルドすることもできます。先ほど作ったtest_bookの中のnotebook.ipynbをPDFにしてみましょう。buildのときに--builder pdfhtmlを指定します。

% cd test_book
% jb build notebooks.ipynb --builder pdfhtml

以下のように表示されたら、PDFの完成です。

こちらの方法では、①で右側に表示されていたバーが表示されていませんでした。

この他にも、「.tex」ファイルを作成したり、 $\LaTeX$ を使用してPDFを作成することもできます。詳しくは公式リファレンスのPDFページをご覧ください。

Jupyter Bookのカスタマイズ

ここまでで「.ipynbや.md」→「HTMLやPDF」という変換をする方法を紹介しました。ここでは、Jupyter Bookのページ内容や構成を変更する方法を取り上げます。ここでのコードは、後ほど取り上げる通りGitHubで公開していますので、コピーなどしたい場合はそちらからご参照ください。

ページの追加

ページを追加するには、ディレクトリに「.ipynb」か「.md」を追加します。ここでは「test_page.ipynb」を作成します。例えば次のような内容で作成します。

_config.yml

_config.ymlを編集します。このファイルは、Jupyter Bookの設定を記述するものです。詳しくは公式リファレンスのconfigページをご覧ください。ここではtitleとauthor、execute_notebooksを編集しました。ついでに、数式を使えるように1番下に追記しました。

_toc.yml

_toc.ymlを編集します。このファイルは、Jupyter Bookの構造を記述するものです。詳しくは公式リファレンスのtocページをご覧ください。ここでは、以下のようなページ構造にしました。

ビルド

追加したページを含めたJupyterBook全体をビルドしましょう。通常のビルドでは、ページのキャッシュが残っており、変更・追加したページしか更新されないため、更新していないページから追加したページへのリンクが表示されません。それを防ぐため、--allオプションを付加してJupyterBook全体を再構成するようにします。

% cd test_book
% jb build --all .

この内容でビルドすると、以下のように表示されます(ここでは次の章で取り扱う1.4も表示されています)。ページの追加と、目次の構成を変えることができました。

MyST Markdown

Jupyter Bookでは、MyST Markdownという拡張されたMarkdownを使用することができます。ここでは個人的に使用頻度が高いDirectivesとRolesについて説明します。

通常のMarkdownについては、Qiita公式のMarkdownの書き方をご覧ください。MyST Markdownにも公式リファレンスとチートシートがあるので、ぜひそちらもご覧ください。

Directives

Directivesは、先ほどの「test page」の1番下にあったようなコンテンツブロックを作成することができる機能です。書式はこの通りです。

directives.mdというファイルを作成して種類と書式を紹介します。以下のように書くと、コンテンツブロックを作成できます。

admonitionは特殊な書式で、自由にタイトルとクラスを設定することができます。この例では:class: tipでtipのコンテンツブロックを指定しています。

code-blockと言語を指定すると、それぞれの言語にそって表示してくれます。

コンテンツブロックはこのように表示されます。ここではコンテンツブロックのなかに、{}内に書くべきワードを書いています。内容がないと、エラーが出てしまうので注意してください。


{code-block}ではなく{code-cell}を指定して、.mdファイルの1番最初にJupytTextというものを記述すると、コードを表示するだけでなく実行結果を表示させることもできます。また、ネストすることも可能です。

toggleを使うと、ボタンで開閉できるスペースを作ることができます。

この他にも多くの書式がありますので、Jupyter BookのMyST Markdownページや、MySTのDirectivesページや、SphinxのDirectivesページをご覧ください。

Roles

RolesはDerectivesと違って、1行でこのように書きます。

例えば以下のように書くと、チェックマークを表示させることができます。


この他にも多くの書式がありますので、MySTのRolesページをご覧ください。

Jupyter Bookの公開

Jupyter BookはHTMLを生成するので、静的Webサイトを構成することができます。ここでは、GitHub Pagesを使ってJupyter Bookを公開してみましょう。

リポジトリの初期設定

GitHubでJupyter Bookのための新しいリポジトリを作ります。以下のページにアクセスしてください。

今回は、test_book_onlineという名前のリポジトリを作りました。Jupyter Bookでリポジトリへのリンクを変更するため、_config.ymlのrepository部を編集します。

ここからリポジトリを設定します。まずmasterブランチの設定を以下のコマンドで行います。ユーザ名やリポジトリ名は自分のものに置き換えてください。

% cd test_book
% git init
% git add .
% git commit -m "adding my first book"
% git remote add origin https://github.com/<ユーザ名>/<リポジトリ名>.git
% git push origin master

これでリポジトリの設定をすることが出来ました。次はPythonのghp-importというパッケージを使ってGitHub Pagesの設定をします。ghp-importがgh-pagesブランチを自動で作ってくれるので、git branch gh-pagesなどを実行する必要はありません。

% pip install ghp-import
% ghp-import -n -p -f _build/html

少し待ったあと、https://<ユーザ名>.github.io/<リポジトリ名> にアクセスすると、test_bookの内容が表示されていると思います。自分の場合は、https://magolors.github.io/test_book_online と置き換えます。

これで公開することが出来ました。

リポジトリの更新

Jupyter Bookのソースコードを更新したいときは、以下のように実行してください。

% cd test_book
% jb build --all .
% git checkout master
% git add .
% git commit -m "comment"
% git push origin master

GitHub Pagesを更新したいときは、以下のように実行してください。git checkout gh-pagesを実行する必要はありません。

% cd test_book
% jb build --all .
% git checkout master
% ghp-import -n -p -f _build/html

この方法の他に、GitHub Actionsを利用してJupyter Bookが更新されると自動でGitHub Pagesも更新するという方法もあります。

最後に

ここまでJupyter Bookの簡単な紹介をしてきました。ここで取り上げたもの以外にも、非常に多くの機能があるので、ぜひ公式リファレンスをご参照ください。また、他にDirectivesの種類があったり、何か間違いなどありましたらコメントにて連絡をお願いします。

ここまで読んでいただきありがとうございました。 面白いと思った方はLGTMを押していただけると励みになります