この記事は何
jupyter bookを使用する際のはじめの手順を調べた際のメモ書きです。
自分の勉強のメモ書きや復習を書き残すためにjupyter bookを使ってみようと思いました。
Jupyter Bookとは
※↑のサイト自体がJupyter Bookで作成されています
Sphinxを用いてjupyter notebookを静的サイトとして出力するツール。 数式の入力やpdfの出力を行うことができる。
pip install jupyter-book にてインストールする。
ページ作成までの流れ
基本的にはドキュメントを参照しつつ、コマンドを順に実行していけば良い。
サンプルページを作成する
参照ページ：Build your book
jupyter-book create mlstudybook/
としてサンプルのjupyter bookができる、この mlstudybook フォルダ以下にビルドに必要なファイルが出力されるので、それぞれ内容を確認する。
jupyter-book build mlstudybook/
として静的サイトジェネレータ（Sphinx v3.2.1）を用いたHTMLが出力される。出力されたページは mlstudybook/_build/index.html にて確認することができる。
ページを追加する
参照ページ：Table of contents structure
マークダウン・ipynbファイルを追加したのち、_toc.yal に各マークダウン・ipynbファイルがどのチャプターで使用されているのかを指定する。例えば、
- file: intro
- part: はじめの章
numbered: true
chapters:
- file: sec-stat/intro
- file: sec-stat/data_description
- file: sec-stat/basic_distribution
- file: sec-stat/statistical_method
- file: sec-stat/hypothesis_tests
- file: sec-stat/linear_model
- part: 次の章
numbered: true
chapters:
- file: sec-table/intro
- file: sec-table/notebooks
と指定された時、intro.mdがトップページになる。次の「はじめの章」の１ページ目はsec-stat/intro.md、「はじめの章」の二節目は sec-stat/data_description.ipynb が使用される。
カスタムのcss/jsを追加する
参照ページ：Custom Sphinx configuration
_static/フォルダ以下に css/jsファイルを追加すると、各ページのヘッダーに自動的に追加される。例えば _static/main.cssと_static/main.js を追加してビルドを実行するとhtmlの <head>~</head> に
<link rel="stylesheet" type="text/css" href="_static/main.css" /> <script src="_static/main.js"></script>
が追記される。
数式の出力・使用できる記法
MyST markdownを使用して記述されたものが認識される。 以下のチートシートを見ながら記述すれば良い。
Vscodeでのnotebookの実行
設定にてjupyter notebookの実行を毎回確認するように設定されていると、 jupyter notebookの実行のたびに確認が入る。 （Working with Jupyter Notebooks in Visual Studio Code）
jupyter book編集時は一時的にこの設定を「Always Trust」に設定しておくと手間が省ける。
例えば、マークダウン領域に
と記述するとビルドしたページでは
と表示される。jupyter notebook内部のマークダウン領域でも同様の処理が適用されるが、 ビルド前のnotebookには表示されないので注意する。
