SphinxのデフォルトテーマAlabasterは驚くほど簡単にカスタマイズできます！（フォントや色の変更、スタイルの上書き）

はじめに

左腕のこれが、仲間の印だ¹🙋‍♂️❌ nikkieです。

Python Boot Camp（a.k.a. pycamp）のライディングページをSphinxで作って得た知見をアウトプットするシリーズです（まだまだ続きますよ〜）。

SphinxでビルドしたHTMLには数々のテーマがありますが、その中のAlabaster²について共有します。

目次

SphinxのAlabasterテーマ

Sphinxは テーマ を使って出力したHTMLの見た目を変更する機能をサポートしています。
テーマというのは、HTMLのテンプレート、スタイルシート、およびその他の静的なファイル類を集めたものです。

ドキュメント変換ツールSphinxが出力するHTMLの見た目に関わるテーマ。
色々なテーマがあり、以下のサイトのようなギャラリーも存在します。

Alabasterはデフォルトと言っても過言ではないテーマです。

sphinx-quickstartでプロジェクトを始めると、Alabasterがconf.pyのhtml_theme³に選択されています⁴。

Alabasterのリポジトリを覗くと、以下のように謳っています。

Alabaster is a visually (c)lean, responsive, configurable theme for the Sphinx documentation system.

この記事でフォーカスするのはconfigurable（訳すなら「設定できる」）という点です。

ランディングページのユースケース：Alabasterテーマのデフォルトのフォントを変えたい

上のリンクを再掲するのでぜひ見ていただきたいのですが、Alabasterテーマには存在感があります。
フォントやリンクのスタイルから、ドキュメンテーションを見て「これ、Alabasterだな」とすぐに分かります。

pycampのランディングページはSphinxで作りましたが、「ひと目でAlabasterとは分からないように設定したい」という個人的なこだわりがありました。
ここでAlabasterのconfigurableが遺憾なく発揮されます！

Sphinxのconf.pyにはhtml_theme_optionsという変数⁵があります。

選択したテーマのルックアンドフィールの設定を行うためのオプションのための辞書です。
どのようなオプションがあるかは、テーマごとに異なります。

このhtml_theme_options（辞書を指す変数）を使って、設定値を上書きできます！

• フォントの設定はfont_family⁶
• リンクの色の設定はlink⁷

ランディングページでの設定値です⁸。

html_theme_options = {
    "font_family": "sans-serif",
    "link": "#4EBBE2",
}

この設定で「ひと目でAlabasterとは分からない」が達成できたんじゃないかなーと感じています。

html_theme_optionsでAlabasterテーマが設定できる仕組み

※隅から隅まで見たわけではないので、ソースコードを追い間違えていたら、教えていただけると嬉しいです。

デフォルト値は https://github.com/bitprophet/alabaster/blob/0.7.12/alabaster/theme.conf にあります。

font_family = Georgia, serif

html_theme_optionsの設定で、デフォルト値を上書きしているようです（このあたりはSphinxのテーマの仕組みをもっと理解できると確信を持てそうです）。

デフォルト値や上書きした値を使ってCSSのテンプレート⁹が埋められます。

body {
    font-family: {{ theme_font_family }};
}

ビルドしたHTMLはこのCSSを読み込むので、（カスタマイズされた）Alabasterテーマが当たるというわけですね！

AlabasterテーマはCSSを置くだけでスタイルをカスタマイズできる

もう一つ「configurableじゃん！」と思った例をご紹介。
既存のクラスにカスタマイズしたスタイルを当てたいとき、CSSを置くだけでOKなんです！

「Custom stylesheet」セクションにあるのですが

Create a file named custom.css anywhere you prefer

custom.cssという名前でCSSを配置すればOK。
慣例により_static/custom.cssとすることが多いみたいです。

細かいことを言うと（※ドキュメントに続いています）

• Alabasterのstatic/alabaster_css_t¹⁰で定義したCSSを上書きできる
• conf.pyのhtml_static_path¹¹の設定が必要

なのですが、CSSファイルを置くだけでスタイルをカスタマイズ可能というのは簡単すぎます！

custom.cssはビルドされたHTML一式が置かれるフォルダにコピーされますし、HTMLにも読み込むタグが追加されます。

この仕組みの存在に気づいたきっかけ

custom.cssを置いていないとき、ビルドしたファイル群の中にcustom.cssというファイルができていたんです！¹²

/* This file intentionally left blank. */

「コメントだけのこのファイル、設定した覚えがないけれど、いったいどこからやってきたんだろう？」と調べていくうちに、custom.cssを置いてスタイルをカスタマイズできることを発見しました！
実際、空のcustom.cssを置くと、ビルドでできたファイル群の中のcustom.cssは空になります。

終わりに

pycampランディングページ作成で知った、「デフォルトテーマのAlabasterはめっちゃconfigurableだぞおおお！」という2点を紹介しました。

• html_theme_optionsを使って、フォントやリンクの色など簡単に細かく変えられる！
• custom.cssを置くだけでAlabasterのスタイルをカスタマイズできる！

SphinxでHTMLに出力しようと思ってsphinx-quickstartをしていたら、すでにテーマにAlabasterが選ばれています。
この記事で紹介したtipsで1人でも多くの方がAlabasterテーマのconfigurableの力を、お手元のSphinxプロジェクトで解き放っていただけたら嬉しいです。
簡単にカスタマイズして、enjoy documentation!!

---

1. アオハルかよおおお！ ↩
2. Alabaster＝雪花石膏。ONE PIECEのアラバスタ（Arabasta）とはちょっと綴りが違います。あれ、スター？🤩（アスタリスク好きの血が騒ぐ）↩
3. テーマの設定に使う変数です。 ref: https://www.sphinx-doc.org/ja/master/usage/configuration.html#confval-html_theme↩
4. https://github.com/sphinx-doc/sphinx/blob/v5.3.0/sphinx/templates/quickstart/conf.py_t#L56↩
5. https://www.sphinx-doc.org/ja/master/usage/configuration.html#confval-html_theme_options↩
6. https://alabaster.readthedocs.io/en/latest/customization.html#fonts↩
7. https://alabaster.readthedocs.io/en/latest/customization.html#style-colors↩
8. https://github.com/pyconjp/pycamp.landing_page/blob/4b57021eb2a3d1d50b6d9a924050c1545a461f39/source/conf.py#L62-L64↩
9. https://github.com/bitprophet/alabaster/blob/0.7.12/alabaster/static/alabaster.css_t#L61 を例としました↩
10. 元のファイル（テンプレート）が https://github.com/bitprophet/alabaster/blob/0.7.12/alabaster/static/alabaster.css_t と認識しています↩
11. https://www.sphinx-doc.org/ja/master/usage/configuration.html#confval-html_static_path↩
12. 元はこちらだと思います：https://github.com/bitprophet/alabaster/blob/0.7.12/alabaster/static/custom.css↩