rustdoc中で数式を書く

rustdocは主にブラウザで閲覧しますが、ブラウザ上で数式をレンダリングする方法としてMathJaxとKaTeXが良く知られています。今回KaTeXを使ってrustdoc中の数式をレンダリングするcrate、katexitを作ったので紹介します

Usage

katexit::katexitというproc-macroが提供されるので：

Cargo.toml

[dependency]
katexit = "0.1.0"

#[cfg_attr(doc, katexit::katexit)]
/// We can write $\LaTeX$ expressions
///
/// Display style
/// -------------
///
/// $$
/// c = \\pm\\sqrt{a^2 + b^2}
/// $$
pub fn my_func() {}

とすれば使えます。$で囲まれた範囲がKaTeXによって認識され数式としてレンダリングされます。$$でディスプレイモードも使えます。KaTeXで使える数式要素については公式のドキュメントを参照してください。

How it works

これは以前紹介したMermaidをrustdoc中で使えるようにするaquamarineのアイデアをそのまま使っています。rustdocのMarkdown to HTMLコンバータはMarkdown中のHTML片をそのままHTMLに埋め込むので、これを使ってKaTeX auto-renderを挿入します。ブラウザは$がそのまま残っているrustdocの生成したHTMLと一緒にKaTeX auto-renderを読み込み、KaTeX auto-renderがそのページ中の$で囲まれた部分を置換します。