めも

メモ.

jupyter bookを用いて本を書いてみる

この記事は何

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がトップページになる。次の「はじめの章」の1ページ目は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」に設定しておくと手間が省ける。

例えば、マークダウン領域に

f:id:misos:20201017184256p:plain

と記述するとビルドしたページでは

f:id:misos:20201017184311p:plain

と表示される。jupyter notebook内部のマークダウン領域でも同様の処理が適用されるが、 ビルド前のnotebookには表示されないので注意する。