Can't build the documentation with Sphinx 9.1.0 - theme error happening

[befeleme]

I'm building the documentation of this project with Sphinx 9.1.0 on Fedora Linux 44, and there's a theme error occurring:

Traceback
=========

      File "/usr/lib/python3.14/site-packages/sphinx/builders/html/__init__.py", line 1238, in handle_page
        raise ThemeError(msg) from exc
    sphinx.errors.ThemeError: An error happened in rendering the page index.
    Reason: TypeError("argument of type '_CascadingStyleSheet' is not a container or iterable")

[mdickinson]

Thanks for the report. Confirmed that I can reproduce here.

We've also seen this on Traits: enthought/traits#1872

I believe the issue is with the enthought_sphinx_theme. It looks as though other people have hit similar issues with other themes - e.g., kai687/sphinxawesome-theme#1464, scipy/scipy#19500. It's possible that we can use some of the same fixes.

[mdickinson]

We have a tentative fix here: enthought/enthought-sphinx-theme#25

[mdickinson]

The theme fix has gone in and a new version of the Enthought Sphinx Theme has been pushed to PyPI. The docs build now passes for me:

~/apptools % uv venv --python 3.14    
Using CPython 3.14.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
~/apptools % uv pip install ".[docs]"
Resolved 25 packages in 543ms
      Built apptools @ file:///Users/mdickinson/Enthought/ETS/apptools
Prepared 1 package in 372ms
Installed 25 packages in 77ms
 + alabaster==1.0.0
 + apptools==5.3.1 (from file:///Users/mdickinson/Enthought/ETS/apptools)
 + babel==2.18.0
 + certifi==2026.1.4
 + charset-normalizer==3.4.4
 + docutils==0.22.4
 + enthought-sphinx-theme==0.7.4
 + idna==3.11
 + imagesize==1.4.1
 + jinja2==3.1.6
 + markupsafe==3.0.3
 + packaging==26.0
 + pygments==2.19.2
 + requests==2.32.5
 + roman-numerals==4.1.0
 + snowballstemmer==3.0.1
 + sphinx==9.1.0
 + sphinxcontrib-applehelp==2.0.0
 + sphinxcontrib-devhelp==2.0.0
 + sphinxcontrib-htmlhelp==2.1.0
 + sphinxcontrib-jsmath==1.0.1
 + sphinxcontrib-qthelp==2.0.0
 + sphinxcontrib-serializinghtml==2.0.0
 + traits==7.1.0
 + urllib3==2.6.3
~/apptools % cd docs
~/apptools/docs % uv run make html
warning: No `requires-python` value found in the workspace. Defaulting to `>=3.14`.
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v9.1.0
loading translations [en]... done
making output directory... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 8 source files that are out of date
updating environment: [new config] 8 added, 0 changed, 0 removed
reading sources... [100%] undo/Introduction
/Users/mdickinson/Enthought/ETS/apptools/docs/source/index.rst:18: WARNING: toctree contains reference to nonexisting document 'api/apptools' [toc.not_readable]
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... 
copying static files... 
Writing evaluated template result to /Users/mdickinson/Enthought/ETS/apptools/docs/build/html/_static/basic.css
Writing evaluated template result to /Users/mdickinson/Enthought/ETS/apptools/docs/build/html/_static/language_data.js
Writing evaluated template result to /Users/mdickinson/Enthought/ETS/apptools/docs/build/html/_static/documentation_options.js
Writing evaluated template result to /Users/mdickinson/Enthought/ETS/apptools/docs/build/html/_static/enthought.css
copying static files: done
copying extra files... 
copying extra files: done
copying assets: done
writing output... [100%] undo/Introduction
generating indices... genindex done
highlighting module code... 
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in build/html.

Build finished. The HTML pages are in build/html.
~/apptools/docs % 

Closing here. Thank you again for the report!