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などに以下を追加してください。
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
jb build
jb buildでJupyter Bookをビルドすることができます。
% cd test_book
% jb build .
公式デモブック
公式デモブックも用意されています。ビルド時にエラーが発生することがあるので、ビルド時の実行をしないオプションを個人的に推奨します。
% git clone https://github.com/executablebooks/quantecon-mini-example
% cd quantecon-mini-example/mini_book
% cat _config.yml
% jb build .
% open /Applications/Google\ Chrome.app _build/html/index.html
PDFを作成する
HTMLと同様に、PDFの作成も簡単にすることができます。2通りの方法があり、少し違いがあります。
① ブラウザから作成する方法
② ビルドして作成する方法
こちらの方法にはpyppeteerが必要なので、インストールします。
% pip install pyppeteer
Jupyter Bookでは、1ページ単位でビルドすることもできます。先ほど作ったtest_bookの中のnotebook.ipynbをPDFにしてみましょう。buildのときに–builder pdfhtmlを指定します。
% cd test_book
% jb build notebooks.ipynb --builder pdfhtml
Jupyter Bookのカスタマイズ
ここまでで「.ipynbや.md」→「HTMLやPDF」という変換をする方法を紹介しました。ここでは、Jupyter Bookのページ内容や構成を変更する方法を取り上げます。ここでのコードは、後ほど取り上げる通りGitHubで公開していますので、コピーなどしたい場合はそちらからご参照ください。
ページの追加
_config.yml
_toc.yml
ビルド
追加したページを含めたJupyterBook全体をビルドしましょう。通常のビルドでは、ページのキャッシュが残っており、変更・追加したページしか更新されないため、更新していないページから追加したページへのリンクが表示されません。それを防ぐため、–allオプションを付加してJupyterBook全体を再構成するようにします。
% cd test_book
% jb build --all .
MyST Markdown
Jupyter Bookでは、MyST Markdownという拡張されたMarkdownを使用することができます。ここでは個人的に使用頻度が高いDirectivesとRolesについて説明します。
通常のMarkdownについては、Qiita公式のMarkdownの書き方をご覧ください。MyST Markdownにも公式リファレンスとチートシートがあるので、ぜひそちらもご覧ください。
Directives
admonitionは特殊な書式で、自由にタイトルとクラスを設定することができます。この例では:class: tipでtipのコンテンツブロックを指定しています。
code-blockと言語を指定すると、それぞれの言語にそって表示してくれます。
この他にも多くの書式がありますので、Jupyter BookのMyST Markdownページや、MySTのDirectivesページや、SphinxのDirectivesページをご覧ください。
Roles
Jupyter Bookの公開
Jupyter BookはHTMLを生成するので、静的Webサイトを構成することができます。ここでは、GitHub Pagesを使ってJupyter Bookを公開してみましょう。
リポジトリの初期設定
GitHubでJupyter Bookのための新しいリポジトリを作ります。以下のページにアクセスしてください。
% 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を押していただけると励みになります