Bookしたい(sphinx_book_theme

$ pip3 install sphinx_book_theme

いま一番気に入っているのがSphinx Book Themeです。 Jupyter Bookで使われているテーマで、Bootstrap5に対応しています。

theme.confを確認すると、pydata_sphinx_themeをベースにしていて、たくさんの[options]が使えることが分かります。

プロジェクトに追加したい

1$ cd プロジェクト名
2$ poetry add --group=docs sphinx
3$ poetry add --group=docs sphinx-book-theme
4$ poetry add --group=docs myst-parser
5$ poetry add --group=docs ablog
6$ sphinx-quickstart docs
7$ code docs/conf.py

poetryを使ってプロジェクトに追加する手順を書き出してみました。 ドキュメント関係のパッケージなので--group=docsに分類しています。

sphinx_book_themeはMySTとABlogと併用できます。 必要はパッケージ(sphinx / sphinx_book_theme / myst_parser / ablog)を追加、 docsにドキュメント用ディレクトリを作成、docs/conf.pyを開いて、以下の設定を追記します。

設定ファイル

1extensions = [
2    ...
3    "sphinx_book_theme",
4    "myst_parser",
5    "ablog",
6    ...
7]
8
9html_theme = "sphinx_book_theme"

拡張(extensions)一覧にパッケージ名を追加します。 また、html_themeをパッケージ名に変更します。

Google Analyticsしたい

1html_theme_options = {
2    "analytics": {"google_analytics_id": "G-xxxxxxxx"},
3}

Sphinx Book ThemePyData Themeを継承しているので、PyData Themeドキュメントを参照します。 Analytics and usage servicesのページにオプションの設定方法が書かれていました。