Jupyter bookの使い方 (Julia言語版)#

このサイトの構築方法について (2020/09/02)。

Julia言語のサイトを構築する方法#

Julia言語でサイトを構築するにはDocumenter.jlやFranklin.jl, Weave.jlなどのパッケージを用いるのが一般的である。これらはMarkdown (.mdや.jmd)などのファイルをHTMLに変換できるが、Jupyter notebookからHTMLに変換するのはやや手間である (と自分は思っているが、今後改善される可能性は十分にある)。詳細は次項で説明するが、このサイトを構築しているJupyter bookはJuliaで完結してはいないものの、より簡単にJupyter notebookをHTMLに変換できる。また、LaTeX形式やpdf形式に変換することもできる (これはWeave.jlでも同じことができるということは述べておく)。

Jupyter bookの導入#

Jupyter bookはSphinxを用いてMarkdownやJupyter notebookからサイトを生成するツールである (以前はJekyllが用いられていた)。Sphinx自体はPythonで書かれた文章作成ツールだが、導入においてPythonコードを編集することは基本的にない。

また、重要な点として、Jupyter notebookのカーネルはPythonでなくてもよいということが挙げられる (Python, R, Julia, Ruby, Go, Scala, Perlなどなど)。カーネルとして用いることのできる言語の一覧はJupyter kernels · jupyter/jupyter Wikiを参照。Python以外の言語を用いている例としてはOther Programming Languagesがある。ここではCoconutというPython製の関数型言語が用いられている。

なお、同じサイト内で異なる言語のカーネルを持つJupyter notebookを元としたページも作成できる (例えばあるページはPython, 次のページはJuliaといったように)。同じページ内で複数の言語を用いるのはまだできないようだが。

とはいえ、Pythonカーネルでやるのが一番楽である。以下にJuliaカーネルを用いる場合の手順を記すが、Pythonカーネルの場合はJuliaのinstallの手順を飛ばせばよい。

1. Anacondaをinstall#

Anaconda または minicondaをinstallする (使用しているOSに応じてinstallerを選択する)。

2. jupyter-notebookをinstall#

pip (またはconda)でJupyter notebookをinstallする。

$ pip install jupyter

installしたTerminal (Windowsならanaconda prompt)でJupyter notebookを立ち上げられることを確認する。

$ jupyter notebook

3. Juliaをinstallし、Ijuliaをinstall#

Juliaをinstallする。次にJuliaを立ち上げて、REPLで]を入力してpkg modeにし、

pkg> add IJulia

によりIjulia.jlをinstallする。この段階で、Jupyter notebookを立ち上げて新規にnotebookを作成する際にJuliaカーネルを選択できるはずである。うまくいっていない場合はJuliaのPATHが通っていないなどが考えられる。

4. jupyter bookをinstall#

pip (またはconda)でjupyter-book をinstallする。

$ pip install jupyter-book

5. テンプレートの作成#

Overview and installationを参照。Terminal (Windowsならanaconda prompt)で次のようにしてテンプレートを作成する。

$ cd hogehoge
$ jupyter-book create mybookname

ただし、mybooknameはサイトの構成ファイルを保存するディレクトリ名であり、変更可能である。jupyter-bookはjbと省略できるので、

$ jb create mybookname

としてもよい。実行後は次のようなファイルがmybooknameの下に生成される。

mybookname/
├── _config.yml
├── _toc.yml
├── content.md
├── intro.md
├── markdown.md
├── notebooks.ipynb
└── references.bib

このうち、Markdownファイル (.md)とJupyter notebookファイル (.ipynb)および参考文献を記述するためのBiBTeXファイル(.bib)が実際のサイトの元ファイルとなる。_config.ymlはサイトの情報を指定するファイルであり、_toc.ymlはサイトの構成を指定するファイルである。また、ディレクトリとファイルの構成例としてquantecon-mini-example (Github pages, Github) が用意されている。

Jupyter bookの機能を確認する場合は先に 8. サイトのbuildを参照。

6. `_config.yml`にサイトの情報を記述#

Configure book settingsを参照。サイトの名前、著者、ロゴ、リポジトリへのリンク、colabで立ち上げるボタンの追加、など様々なことが設定できる。

7. `_toc.yml`にサイトの構成を記述#

Table of Contents structureを参照。各ファイルをどのような構成でサイトに変換するか、ということを指定する。

8. サイトのbuild#

コンテンツを含むディレクトリを./mybooknameとしたとき

jb build mybookname

によりbuildする。このとき、Jupyter notebookはbuild時に実行される。Ijulia.jlが入っていなかったり、実行不可能であればエラーが生じる。build完了後、./build/htmlというディレクトリの下に他の依存ファイルを含めたサイトのHTMLが生成される。

9. GitHub pagesでサイトを公開する#

./build/htmlの中身を同じリポジトリのgh-pagesブランチにcommitするか、別のリポジトリを用意してcommitする。本サイトの場合はコンテンツの管理はhttps://github.com/compneuro-julia/compneuro-julia-managementで、サイトのホスティングはhttps://github.com/compneuro-julia/compneuro-julia.github.ioで行っている。

なお、GitHub pagesはデフォルトではJekyllで処理されるので、.nojekyllという名前の空ファイルを作成しておく (空ファイルだとuploadされない場合もあるので注意)。

GitHub Pagesで普通の静的ホスティングをしたいときは .nojekyll ファイルを置く - Qiita

MyST Markdown形式について#

Jupyter bookは通常のMarkdown記法に加え、MyST (Markedly Structured Text)と呼ばれる形式のMarkdown記法に対応している。例えば

```{note}
これはノートです。
```

と記述すれば次のように変換される。

Note

これはノートです。

これはMarkdownファイルにも、Jupyter notebookのMarkdown cellにも記述できる。詳細はMyST Markdown OverviewやMyST Cheat Sheetなどを参照 (特に後者はMySTでどのようなことができるか一目でわかる)。

数式について#

通常のMarkdownやJupyter notebookと同様に行える。次のように入力すれば

$$
F(\omega) = \cfrac{1}{\sqrt{2\pi}}\int_{-\infty}^{+\infty}f(t)e^{i\omega t}dt
$$

以下のように出力される。

\[ F(\omega) = \cfrac{1}{\sqrt{2\pi}}\int_{-\infty}^{+\infty}f(t)e^{i\omega t}dt \]

入力・出力を隠す#

Jupyter notebookのcellのtagを変更してcellの入力や出力を隠すことができる。Tagの変更はJupyter notebookでView > Cell Toolbar > Tagsとすることで各cellにtagを追加する欄が表示される。詳細はHiding cell contentsを参照。

Syntax highlightingについて#

Sphinxはコードの構文解析をPygmentsによって行っている (cf. sphinx/highlighting.py)。これまでは全てPythonLexerでsyntax highlightされていたが、Jupyter book v0.8.0でMyST-NBのv0.10に対応し、Jupyter notebookのカーネルの言語に応じてcode cellがsyntax highlightされるようになった。

Change Log - Jupyter book v0.8.0 2020-09-01

Syntax highlightの色などはカスタムCSSの追加して調整している (Qiitaの配色が見やすいので参考にした)。具体的な調整についてはhttps://compneuro-julia.github.io/_static/custom.cssおよび次項を参照。

カスタムCSSの追加#

本の構成が

mybook/
├── _config.yml
├── _toc.yml
└── page1.md

のようであった場合、

mybook/
├── _config.yml
├── _toc.yml
├── page1.md
└── _static
    └── myfile.css

のように _staticディレクトリを作成し、その下にCSSやJavascriptなどのファイルを置いておけばbuildするときに自動で読み込まれる。 _staticディレクトリには他に画像ファイルやpdfファイルなどを置くことも可能である。今回、試験的にfontにJuliaMonoを用いた。custom.cssに以下を記述し、fontにJuliaMono-Regularを指定した。

@font-face {
    font-family: JuliaMono-Regular;
    src: url("https://cdn.jsdelivr.net/gh/cormullion/juliamono/webfonts/JuliaMono-Regular.woff2");
}

Juliaで学ぶ計算論的神経科学

Jupyter bookの使い方 (Julia言語版)

Contents