KeyError when trying to build almost empty docs

[funkyfuture]

hello, i'm trying to port an existing Sphinx-powered documentation to use this theme and i'm hitting some problems. therefore i set up a fresh Sphinx project for fiddling around, but with hardly any contents, the build fails.

steps to reproduce:

1. set up and activate a virtual environment
2. pip install sphinx-immaterial
3. sphinx-quickstart
4. add sphinx_immaterial to extensions and set as HTML theme
5. make html

Sphinx error log

# Platform:         linux; (Linux-5.19.0-38-generic-x86_64-with-glibc2.35)
# Sphinx version:   6.1.3
# Python version:   3.11.2 (CPython)
# Docutils version: 0.19
# Jinja2 version:   3.1.2
# Pygments version: 2.15.0

# Last messages:
#   reading sources... [100%] index
#   
#   looking for now-outdated files...
#   none found
#   pickling environment...
#   done
#   checking consistency...
#   done
#   preparing documents...
#   failed

# Loaded extensions:
#   sphinx.ext.mathjax (6.1.3)
#   sphinxcontrib.applehelp (1.0.4)
#   sphinxcontrib.devhelp (1.0.2)
#   sphinxcontrib.htmlhelp (2.0.1)
#   sphinxcontrib.serializinghtml (1.1.5)
#   sphinxcontrib.qthelp (1.0.3)
#   alabaster (0.7.13)
#   sphinx_immaterial.css_and_javascript_bundles (unknown version)
#   sphinx_immaterial.external_resource_cache (unknown version)
#   sphinx_immaterial.google_fonts (unknown version)
#   sphinx_immaterial.apidoc.apidoc_formatting (unknown version)
#   sphinx_immaterial.apidoc.python.parameter_objects (unknown version)
#   sphinx_immaterial.apidoc.python.strip_property_prefix (unknown version)
#   sphinx_immaterial.apidoc.python.type_annotation_transforms (unknown version)
#   sphinx_immaterial.apidoc.python.strip_self_and_return_type_annotations (unknown version)
#   sphinx_immaterial.apidoc.python.default (unknown version)
#   sphinx_immaterial.apidoc.cpp.signodes (unknown version)
#   sphinx_immaterial.apidoc.cpp.strip_namespaces_from_signatures (unknown version)
#   sphinx_immaterial.apidoc.cpp.cpp_resolve_c_xrefs (unknown version)
#   sphinx_immaterial.apidoc.cpp.default (unknown version)
#   sphinx_immaterial.nav_adapt (unknown version)
#   sphinx_immaterial.postprocess_html (unknown version)
#   sphinx_immaterial.apidoc.object_description_options (unknown version)
#   sphinx_immaterial.apidoc.object_toc (unknown version)
#   sphinx_immaterial.search_adapt (unknown version)
#   sphinx_immaterial.apidoc.wrap_signatures (unknown version)
#   sphinx_immaterial.apidoc.generic_synopses (unknown version)
#   sphinx_immaterial.content_tabs (unknown version)
#   sphinx_immaterial.mermaid_diagrams (unknown version)
#   sphinx_immaterial.task_lists (unknown version)
#   sphinx_immaterial.code_annotations (unknown version)
#   sphinx_immaterial.default_literal_role (unknown version)
#   sphinx_immaterial.highlight_push_pop (unknown version)
#   sphinx_immaterial.inline_icons (unknown version)
#   sphinx_immaterial.custom_admonitions (unknown version)
#   sphinx_immaterial (unknown version)

# Traceback:
Traceback (most recent call last):
  File "/home/user/.virtualenvs/immaterial-tests/lib/python3.11/site-packages/sphinx/cmd/build.py", line 284, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/user/.virtualenvs/immaterial-tests/lib/python3.11/site-packages/sphinx/application.py", line 347, in build
    self.builder.build_update()
  File "/home/user/.virtualenvs/immaterial-tests/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 311, in build_update
    self.build(to_build,
  File "/home/user/.virtualenvs/immaterial-tests/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 377, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/user/.virtualenvs/immaterial-tests/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 571, in write
    self.prepare_writing(docnames)
  File "/home/user/.virtualenvs/immaterial-tests/lib/python3.11/site-packages/sphinx/builders/html/__init__.py", line 472, in prepare_writing
    self.load_indexer(docnames)
  File "/home/user/.virtualenvs/immaterial-tests/lib/python3.11/site-packages/sphinx/builders/html/__init__.py", line 940, in load_indexer
    self.indexer.load(ft, self.indexer_format)
  File "/home/user/.virtualenvs/immaterial-tests/lib/python3.11/site-packages/sphinx_immaterial/search_adapt.py", line 179, in load
    docurls = frozen["docurls"]
              ~~~~~~^^^^^^^^^^^
KeyError: 'docurls'

[funkyfuture]

addendum, when i do the same, but with an editable installation of the current main branch, it yields:

Running Sphinx v6.1.3
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 2 source files that are out of date
updating environment: [new config] 2 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                                                                                          
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
failed

Extension error (sphinx_immaterial.css_and_javascript_bundles):
Handler <function generate_bundles at 0x7f59aa113920> for event 'env-check-consistency' threw an exception (exception: [Errno 2] No such file or directory: '/home/user/sphinx-immaterial/sphinx_immaterial/bundles/stylesheets/main.css')
make: *** [Makefile:20: html] Error 2

the …/sphinx_immaterial/bundles directory exists nowhere.

[jbms]

The first error is fixed by deleting your old build directory. The second error is because you need to run the nodejs-based build step. Did you use pip install -e . to create the editable install?

[2bndy5]

As for the absent sphinx_immaterial/bundles folder, that should be generated at install time with

npm install
npm run build

executed from setup.py.

[funkyfuture]

The first error is fixed by deleting your old build directory.

maybe i oversaw it, but a hint that a clean is always required would be helpful then. or, if it's a requirement, should the builder make sure of it?

Did you use pip install -e . to create the editable install?

indeed, but the static_bundles command isn't invoked.

otherwise that helped to get started, thanks!

[2bndy5]

The first error is fixed by deleting your old build directory.

maybe i oversaw it, but a hint that a clean is always required would be helpful then. or, if it's a requirement, should the builder make sure of it?

We often see this when the old build used a different theme. I don't think of it as a requirement, rather good practice to start a fresh build when switching themes (or testing mods of a theme).

[funkyfuture]

rather good practice to start a fresh build when switching themes (or testing mods of a theme).

a'ight, i'll propose an addition for the Getting Started section.

[jbms]

In this case the issue is due to the sphinx-immaterial monkey patching of the search index generation code in Sphinx. In fact it could make sense to add something to the search index code to deal with this automatically, since quite a few users have run into this issue.

[tunchunairarko]

Hi,

has the issue been resolved yet? I am still facing this same issue.

[2bndy5]

The current solution is to purge any previous docs build. Are you switching from a different theme? That seems to be the most likely culprit here.

[2bndy5]

I'm closing this as the problem was 2 issues:

1. This theme needs a clean build env when migrating from a different sphinx theme. This was solved by adding information to the docs' landing page (Extends docs with hint when migrating #239)
2. pip install -e . no longer invokes npm run build. This is being tracked in a separate issue; see Editable install no longer runs nodejs build step #249