Docs.rsで数式を使う(KaTeX)

TL;DR

リポジトリのルートにkatex.html置いて、Cargo.tomlに

[package.metadata.docs.rs]
rustdoc-args = [
    "--html-in-header",
    "katex.html",
]

を追加する。

前置き

Rustはドキュメント生成や、ドキュメント中のコードのテストが簡単に出来る(cargo doc, cargo test)のでドキュメントを書きやすい。しかし、デフォルトではドキュメント中に数式を使えない(はず)。ドキュメント中に数式を書きたいことはよくあるので私が以前から使っている方法を紹介する。

選択した手法

調べると以下のような情報が得られる。

https://stackoverflow.com/questions/46495063/how-to-write-math-formulas-for-rust-documentation
https://github.com/paulkernfeld/rustdoc-katex-demo
https://github.com/CAD97/katex-doc
https://github.com/victe/rust-latex-doc-minimal-example

この中で https://github.com/CAD97/katex-doc を採用した。
なぜなら、$`hoge`$ という形で数式を書くため、Markdownで使われている記号(_, *, []など)のエスケープを気にせずに書けるためである。

使い方

ローカル

katex.html をリポジトリのルートに置き、cargo docでKaTeXを無効にした状態で依存クレートを含めたドキュメントを作成し、cargo rustdoc -- --html-in-header katex.html でリポジトリのクレートのみKaTeXを有効にしてドキュメントを作成する。

依存クレートのドキュメントが不要な場合は、RUSTDOCFLAGS="--html-in-header katex.html" cargo doc --no-deps で生成できる。

docs.rs

docs.rsでのドキュメント作成時にKaTeXを有効にした場合は、Cargo.tomlに以下の内容を追記する。

Cargo.toml

[package.metadata.docs.rs]
rustdoc-args = [
    "--html-in-header",
    "katex.html",
]

ローカルの場合でも、docs.rsの場合でも、katex.htmlをリポジトリルート以外に置いたり、ファイルを違う名前で作成した場合は適宜パスを変更する必要がある。

後書き

KaTeXは2021年7月25日現在最新版は0.13.13なので、実際使われる際は0.9.0から最新のものに変えたほうが良いかもしれません。(手動で更新するのは面倒なのでなにか良い方法あれば教えて下さい。)
間違っている点や、他に良い方法などあればコメントして下さい。

追記

0.13.13を使いたい場合は、このkatex.htmlを使えば良いです。