環境

Python3.11.2
sphinx v6.1.3
pydata-sphinx-theme v0.13.0

背景

sphinxでドキュメントを生成しています。

エラー

pydata-sphinx-themeをv0.12.0からv0.13.0にバージョンアップしたら、ドキュメント生成時にイベント～のハンドラ 'builder-inited' で例外が発生しました。 (exception: 'icon_links')というエラーが発生しました。

docs/conf.py

project = "bar"
copyright = "2020"
author = "alice"
language = "ja"
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

html_theme = "pydata_sphinx_theme"

html_theme_options = {
    "github_url": "https://github.com/foo/bar",
}

$ cd docs
# `-T`でトレースバックを出力
$ sphinx-build . _build/ -T
Sphinx v6.1.3 を実行中
翻訳カタログをロードしています [ja]... 完了
保存された環境データを読み込み中... 完了

Traceback (most recent call last):
  File "/workspaces/annofab-cli/.venv/lib/python3.11/site-packages/sphinx/events.py", line 96, in emit
    results.append(listener.handler(self.app, *args))
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/workspaces/annofab-cli/.venv/lib/python3.11/site-packages/pydata_sphinx_theme/__init__.py", line 202, in update_config
    theme_options["icon_links"].insert(
    ~~~~~~~~~~~~~^^^^^^^^^^^^^^
KeyError: 'icon_links'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/workspaces/annofab-cli/.venv/lib/python3.11/site-packages/sphinx/cmd/build.py", line 279, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/workspaces/annofab-cli/.venv/lib/python3.11/site-packages/sphinx/application.py", line 262, in __init__
    self._init_builder()
  File "/workspaces/annofab-cli/.venv/lib/python3.11/site-packages/sphinx/application.py", line 335, in _init_builder
    self.events.emit('builder-inited')
  File "/workspaces/annofab-cli/.venv/lib/python3.11/site-packages/sphinx/events.py", line 107, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: イベント <function update_config at 0x7f0f624ff880> のハンドラ 'builder-inited' で例外が発生しました。 (exception: 'icon_links')

Extension error (pydata_sphinx_theme):
イベント <function update_config at 0x7f0f624ff880> のハンドラ 'builder-inited' で例外が発生しました。 (exception: 'icon_links')

原因

pydata-sphinx-themev0.13.0のバグのようです。

対策

html_theme_optionsdictにicon_linksキーの空listを追加することで、sphinx-buildコマンドはエラーなくドキュメントを生成することができました。

docs/conf.py

project = "bar"
copyright = "2020"
author = "alice"
language = "ja"
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

html_theme = "pydata_sphinx_theme"

html_theme_options = {
    "github_url": "https://github.com/foo/bar",
    "icon_links": []
}