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
スクリーンショット 2021-01-14 22.33.26.png

jb build

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

% cd test_book
% jb build .
スクリーンショット 2021-01-13 21.09.46.png

公式デモブック

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

% git clone https://github.com/executablebooks/quantecon-mini-example
% cd quantecon-mini-example/mini_book
% cat _config.yml
スクリーンショット 2021-01-14 22.40.49.png
% jb build .
% open /Applications/Google\ Chrome.app _build/html/index.html
スクリーンショット 2021-01-14 3.01.12.png

PDFを作成する

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

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

スクリーンショット 2021-01-14 16.44.38.png

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

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

% pip install pyppeteer

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

% cd test_book
% jb build notebooks.ipynb --builder pdfhtml
スクリーンショット 2021-01-14 16.51.04.png

Jupyter Bookのカスタマイズ

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

ページの追加

スクリーンショット 2021-01-15 23.32.30.png

_config.yml

スクリーンショット 2021-01-16 15.38.11.png

_toc.yml

スクリーンショット 2021-01-14 23.12.18.png

ビルド

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

% cd test_book
% jb build --all .
スクリーンショット 2021-01-15 23.36.32.png

MyST Markdown

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

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

Directives

スクリーンショット 2021-01-16 13.55.38.png

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

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

スクリーンショット 2021-01-16 15.41.23.png
スクリーンショット 2021-01-29 18.14.55.png

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

Roles

スクリーンショット 2021-01-16 14.18.30.png

Jupyter Bookの公開

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

リポジトリの初期設定

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

 

スクリーンショット 2021-01-16 15.39.08.png
% 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を押していただけると励みになります

广告
将在 10 秒后关闭
bannerAds