Rustdoc の CSS ことはじめ

本記事は Rust Advent Calendar 2023 シリーズ 2 の5日目の記事です。

本記事では、Rustdoc の見栄えを調整するCSSをカスタマイズするためのオプションと簡単な作成例を解説します。

オプションの種類について

2023年12月現在、CSSをカスタマイズするオプションは以下の3つがあります¹。

Option	Desc
--theme	渡した CSS の内容を Theme として追加する。
--extend-css	渡した CSS の内容を theme.css の末尾に追加する。
--markdown-css	渡した CSS の内容を適用するための link 要素を追加する。

Rustdocには、Theme と呼ばれるCSSで記述された配色パターンが用意されており、オプションを利用することで、追加及びその一部を上書きすることができます。

ちなみに標準ライブラリの Rustdoc に採用されている Theme は以下から確認・変更できます。
https://doc.rust-lang.org/settings.html

Theme はドキュメント右上の歯車アイコン及び設定画面から確認・変更することができます。
システムの設定がライトモードの場合は light theme 、ダークモードの場合は dark theme を自動的に適用してくれる設定もありますので、色関連の変更は既存のテーマに依存しない --theme 及び、デフォルトのテーマを指定することができる --default-theme を利用するのがおすすめです。

とはいえ、いきなり Theme の内容を全て網羅するのは大変だと思いますので、まずはお手軽な --extend-css で試してみるのがいいかもしれません。

オプションの利用と適用の例

今回は --extend-css を利用してCSSをカスタマイズしてみましょう。
まずは Cargo を利用して Rust のプロジェクトを作成します。

cargo new --lib rustdoc_css

src/lib.rs はどのような内容でも問題ありませんが、今回はわかりやすく以下のようにしておきます。

/// hello モジュールです。
pub mod hello {
    /// world 関数です。
    pub fn world() {
        println!("Hello, World!");
    }
}

一旦この状態でコマンドラインからドキュメントを生成してみましょう。

# cargo rustdoc の場合
cargo rustdoc

# cargo doc の場合
cargo doc

現在のCSSはまだデフォルトであるため、ドキュメントの出力結果は以下のようになるはずです。

ではここから CSS を用意して、一部の文字の色を変更してみましょう。
文字の色の変更方法は色々あると思いますが、今回は :root を上書いていこうと思います。

extend.css

:root {
    --link-color: aquamarine;
    --mod-link-color: aquamarine;
    --sidebar-link-color: aquamarine;
}

CSSが用意できたら、コマンドラインからオプションを利用して、適用してみましょう。

# cargo rustdoc の場合
cargo rustdoc -- --extend-css ./extend.css

# cargo doc の場合
RUSTDOCFLAGS="--extend-css share/docs/extend.css" cargo doc

うまくいけば以下のような出力になるはずです。

このように、ファイルを用意してオプションで指定するだけで、非常に手軽に CSS を適用することができます。
今回の例は文字の色の変更でしたが、普通のHTMLと同じく背景色を変更したり、オブジェクトに好みの margin を適用したり、なんてことも可能です。

色々カスタマイズして自分好みのドキュメントを作成してみるのも面白いかもしれません。

～ おしまい ～

1. https://doc.rust-lang.org/rustdoc/command-line-arguments.html ↩