`pydata-sphinx-theme` v0.17 breaks with `sphinx` 9.1.0

[kif]

Hi,
My CI spotted a regression when building the documentation.
With pydata-sphinx-theme v0.16.1, the documentation builds OK, regardless if the version of sphinx is 8 or 9.

My favorite LLM suggests:
Based on the error, I can see the issue: pydata-sphinx-theme v0.17 is not compatible with Sphinx 9.1.0. The code is trying to access app.builder which no longer exists in newer Sphinx versions.
Starting with Sphinx 9.0, the timing of when app.builder becomes available has changed. The pydata-sphinx-theme v0.17 tries to access app.builder.theme_options too early in the initialization process, before the builder attribute exists on the Sphinx object.

I hope this will allow you to fix the error.

Here is the traceback:

Versions
========

* Platform:         linux; (Linux-6.1.0-17-amd64-x86_64-with-glibc2.41)
* Python version:   3.13.1 (CPython)
* Sphinx version:   9.1.0
* Docutils version: 0.21.2
* Jinja2 version:   3.1.6
* Pygments version: 2.19.1

Last Messages
=============

None.

Loaded Extensions
=================

None.

Traceback
=========

    Traceback (most recent call last):
      File "/users/kieffer/.venv/py313/lib/python3.13/site-packages/sphinx/cmd/build.py", line 414, in build_main
        app = Sphinx(
            srcdir=args.sourcedir,
        ...<14 lines>...
            exception_on_warning=args.exception_on_warning,
        )
      File "/users/kieffer/.venv/py313/lib/python3.13/site-packages/sphinx/application.py", line 299, in __init__
        self.setup_extension(extension)
        ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
      File "/users/kieffer/.venv/py313/lib/python3.13/site-packages/sphinx/application.py", line 505, in setup_extension
        self.registry.load_extension(self, extname)
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
      File "/users/kieffer/.venv/py313/lib/python3.13/site-packages/sphinx/registry.py", line 569, in load_extension
        metadata = setup(app)
      File "/users/kieffer/.venv/py313/lib/python3.13/site-packages/pydata_sphinx_theme/__init__.py", line 293, in setup
        theme_options = utils.get_theme_options_dict(app)
      File "/users/kieffer/.venv/py313/lib/python3.13/site-packages/pydata_sphinx_theme/utils.py", line 23, in get_theme_options_dict
        if hasattr(app.builder, "theme_options"):
                   ^^^^^^^^^^^
    AttributeError: 'Sphinx' object has no attribute 'builder'. Did you mean: 'build'?

Best'

Jerome

[drammock]

yikes. Thank you for reporting.

[wxtim]

I have come across this with Sphinx 8.2.3

[Yann-P]

From what I tested, this is not specific to the version of Sphinx (which explains why wxtim had the issue with an older version)

uv run --no-project \
    --with "pydata-sphinx-theme==${SPHINX_VERSION}" \
    --with "sphinx==9.1.0" \
  sphinx-build -C \
    -D "extensions=pydata_sphinx_theme"  \
    -D "html_theme=pydata_sphinx_theme" \
    -D "master_doc=index" \
    docs docs/_build/html -b html

fails for every sphinx version down to the least supported version, 7.0.0.

Instead, it looks like a 0.17.0 regression when handling sphinx's config extensions=['pydata_sphinx_theme'].

I linked a PR that attempts to fix this.