これは数値計算Advent Calendar23日目の記事です！クリスマスまでもう少しですね。
私は以前の記事
でも紹介したeomというRustのライブラリを作っています。このライブラリは
- 常微分方程式、偏微分方程式（スペクトル法）の計算
- 力学系解析（リアプノフ指数、共変リアプノフベクトル）の計算
のためのライブラリです。
このライブラリは私の作ってる他のRustのライブラリに比べて数学的な側面が強いので、cargo docで生成されるライブラリとしてのリファレンスに加えて、数学的な側面を補足するbookを作っています。今回はAdCのためにこの日本語版を新たに書き始めました（できたとは言っていない）。
数値計算の内容はbookを見てもらうとして、この記事ではせっかくなのでbookの作り方と管理方法についてまとめます。
mdbook
先程からbookと言ってるのは「本」と呼ぶと個人的な違和感が強いからですが、プログラミング関係のコミュニティではHTMLで生成されたまとまったドキュメントのことをbookと呼ぶ事が最近は多いように感じます。
eom bookではこのようなbookを生成するためのツールとしてmdbookを使っています。
mdbookの説明中にもあるようにこのようにMarkdownからbookを作るツールとしてはGitbookが有名なようですね（使ったこと無い)。mdbookはRust製で公式のリポジトリで開発されていることもあり、Rust製ツールでは良く使われています。
Install
他のRust製ツールと同様に
cargo install mdbook
で入ります。依存しているプロジェクトが多いのでビルドにはちょっと時間がかかります…これで$HOME/.cargo/bin/mdbookに実行ファイルがインストールされるはずです。
設定
mdbookの設定はTOMLを使って記述します
[book]
authors = ["Toshiki Teramura"]
src = "src"
title = "eom"
[output.html]
mathjax-support = true
概ね設定は名前の通りですが、設定でMathJaxを有効にすることができます。
ただし数式を出力するにはMarkdownからHTMLに変換した上でHTML内に埋め込まれている数式をMathJaxがレンダリングするため、エスケープが少しややこしい事になります。
ここで\\(x_n \in \mathbb{R}^N \\)はN次元のベクトル
インラインの数式はこの様な感じになります。MathJaxなのでLaTeXの命令もある程度使えます。Displayモードの時はこんな感じ：
\\[
\begin{align}
\frac{dx}{dt} &= -p x + py \\\\
\frac{dy}{dt} &= -xz + rx -y \\\\
\frac{dz}{dt} &= xy - bz
\end{align}
\\]
align環境も使えますが、改行が\をそれぞれエスケープしないといけないので4文字になってます（いまいちルールが分かりきってない）
Build
mdbook build
とするとbook.tomlに従ってHTMLを含むディレクトリbook/を作ってくれます。また、
mdbook serve
とするとHTTPサーバーを起動した上でsrc/以下を監視してファイルが更新される毎にHTMLを再生成してくれます（便利）。
GitLab Pages
ビルドされたbookはGitLab Pagesにアップロードされています。
GitLab Pagesは静的なサイトを公開する事ができるサービスで、GitLabのリポジトリに紐づいています。
例えばgitlab.com/termoshtt/eomのリポジトリのGitLab Pagesはhttp://termoshtt.gitlab.com/eomに公開されます。
GitLab CI
使い方はGitLab自体でCIを管理してくれているのでGitHub Pages等より特に認証周りが簡単で、CIにpagesというJobを追加すると、public/ディレクトリを自動的に公開してくれます。
GitLab CI自体DockerコンテナベースのCIサービスで、GitLabはgitlab.comに無料でリポジトリを作れますが、同時にCIも無料で使えます。オンプレ環境にGitLabを入れて使っている場合も同様です。
最後に
本当はデータ同化のライブラリda.rsの日本語版も含めて公開する予定だったのですが、そもそもライブラリの実装状況も含めて進捗ダメでした。