Bug located in ansys/doc-build@v8

[da1910]

🔍 Before submitting the issue

• I have searched among the existing issues
• I am using a Python virtual environment

🐞 Description of the bug

Our CI fails when upgrading the sphinx theme to 1.2.0 with the following error:

Extension error (ansys_sphinx_theme.search.fuse_search):
Handler <function create_search_index at 0x7f82c7d3a4d0> for event 'build-finished' threw an exception (exception: list index out of range)
make: *** [Makefile:19: html] Error 2

📝 Steps to reproduce

https://github.com/ansys/grantami-bomanalytics/actions/runs/11619612949/job/32359611095?pr=640

Build the documentation for grantami-bomanalytics with Ansys sphinx theme 1.2.0

💻 Which operating system are you using?

Linux

📀 Which ANSYS version are you using?

n/a

🐍 Which Python version are you using?

3.10

📦 Installed packages

Installing dependencies from lock file

Package operations: 118 installs, 1 update, 0 removals

• Installing attrs (24.2.0)
• Installing rpds-py (0.20.0)
• Installing referencing (0.35.1)
• Installing six (1.16.0)
• Installing jsonschema-specifications (2024.10.1)
• Installing platformdirs (4.3.6)
• Installing python-dateutil (2.9.0.post0)
• Installing traitlets (5.14.3)
• Installing types-python-dateutil (2.9.0.20241003)
• Installing arrow (1.3.0)
• Installing fastjsonschema (2.20.0)
• Installing jsonschema (4.23.0)
• Installing jupyter-core (5.7.2)
• Installing pycparser (2.22)
• Installing tornado (6.4.1)
• Installing pyzmq (26.2.0)
• Installing cffi (1.17.1)
• Installing fqdn (1.5.1)
• Installing idna (3.10)
• Installing isoduration (20.11.0)
• Installing jsonpointer (3.0.0)
• Installing jupyter-client (8.6.3)
• Installing markupsafe (3.0.2)
• Installing nbformat (5.10.4)
• Installing ptyprocess (0.7.0)
• Installing rfc3339-validator (0.1.4)
• Installing rfc3986-validator (0.1.1)
• Installing soupsieve (2.6)
• Installing uri-template (1.3.0)
• Installing webcolors (24.8.0)
• Installing webencodings (0.5.1)
• Installing argon2-cffi-bindings (21.2.0)
• Installing asttokens (2.4.1)
• Installing beautifulsoup4 (4.12.3)
• Installing bleach (6.1.0)
• Installing certifi (2024.8.30)
• Installing charset-normalizer (3.4.0)
• Installing cryptography (43.0.3)
• Installing defusedxml (0.7.1)
• Installing exceptiongroup (1.2.2)
• Installing executing (2.1.0)
• Installing jinja2 (3.1.4)
• Installing jupyterlab-pygments (0.3.0)
• Installing mistune (3.0.2)
• Installing nbclient (0.10.0)
• Installing packaging (24.1)
• Installing pandocfilters (1.5.1)
• Installing parso (0.8.4)
• Installing pure-eval (0.2.3)
• Installing pygments (2.18.0)
• Installing python-json-logger (2.0.7)
• Installing pyyaml (6.0.2)
• Installing sniffio (1.3.1)
• Installing terminado (0.18.1)
• Installing tinycss2 (1.4.0)
• Installing typing-extensions (4.12.2)
• Installing urllib3 (2.2.3)
• Installing wcwidth (0.2.13)
• Installing anyio (4.6.2.post1)
• Installing argon2-cffi (23.1.0)
• Installing decorator (5.1.1)
• Installing h11 (0.14.0)
• Installing jedi (0.19.1)
• Installing jupyter-events (0.10.0)
• Installing jupyter-server-terminals (0.5.3)
• Installing matplotlib-inline (0.1.7)
• Installing nbconvert (7.16.4)
• Installing overrides (7.7.0)
• Installing pexpect (4.9.0)
• Installing prometheus-client (0.21.0)
• Installing prompt-toolkit (3.0.48)
• Installing pyspnego (0.11.1)
• Installing requests (2.32.3)
• Installing send2trash (1.8.3)
• Installing stack-data (0.6.3)
• Installing websocket-client (1.8.0)
• Installing babel (2.16.0)
• Installing comm (0.2.2)
• Installing debugpy (1.8.7)
• Installing httpcore (1.0.6)
• Installing iniconfig (2.0.0)
• Installing ipython (8.29.0)
• Installing json5 (0.9.25)
• Installing jupyter-server (2.14.2)
• Installing nest-asyncio (1.6.0)
• Installing pluggy (1.5.0)
• Installing psutil (6.1.0)
• Installing pyparsing (3.2.0)
• Installing requests-ntlm (1.3.0)
• Installing tomli (2.0.2)
• Installing ansys-openapi-common (2.2.0)
• Installing async-lru (2.0.4)
• Installing coverage (7.6.4)
• Installing elementpath (4.5.0)
• Installing httpx (0.27.2)
• Installing ipykernel (6.29.5)
• Installing jupyter-lsp (2.2.5)
• Installing jupyterlab-server (2.27.3)
• Installing jupyterlab-widgets (3.0.13)
• Installing mypy-extensions (1.0.0)
• Installing notebook-shim (0.2.4)
• Installing numpy (2.1.2)
• Installing pytest (8.3.3)
• Installing pytz (2024.2)
• Updating setuptools (65.5.0 -> 75.2.0)
• Installing tenacity (9.0.0)
• Installing tzdata (2024.2)
• Installing widgetsnbextension (4.0.13)
• Installing ansys-grantami-bomanalytics-openapi (3.1.0rc1)
• Installing ipywidgets (8.1.5)
• Installing jupyterlab (4.3.0)
• Installing lxml (5.3.0)
• Installing mypy (1.13.0)
• Installing pandas (2.2.3)
• Installing plotly (5.24.1)
• Installing pytest-cov (6.0.0)
• Installing requests-mock (1.12.1)
• Installing tabulate (0.9.0)
• Installing xmlschema (3.4.2)

Installing the current project: ansys-grantami-bomanalytics (2.2.0dev0)
Run source .venv/bin/activate
Installing dependencies from lock file

Package operations: 47 installs, 0 updates, 0 removals

• Installing natsort (8.4.0)
• Installing alabaster (0.7.16)
• Installing docutils (0.21.2)
• Installing domdf-python-tools (3.9.0)
• Installing imagesize (1.4.1)
• Installing mdurl (0.1.2)
• Installing more-itertools (10.5.0)
• Installing snowballstemmer (2.2.0)
• Installing sphinxcontrib-applehelp (2.0.0)
• Installing sphinxcontrib-devhelp (2.0.0)
• Installing sphinxcontrib-htmlhelp (2.1.0)
• Installing sphinxcontrib-jsmath (1.0.1)
• Installing sphinxcontrib-qthelp (2.0.0)
• Installing sphinxcontrib-serializinghtml (2.0.0)
• Installing accessible-pygments (0.0.5)
• Installing apeye-core (1.1.5)
• Installing cssutils (2.11.1)
• Installing filelock (3.16.1)
• Installing markdown-it-py (3.0.0)
• Installing msgpack (1.1.0)
• Installing pillow (11.0.0)
• Installing ruamel-yaml-clib (0.2.12)
• Installing sphinx (8.1.3)
• Installing zipp (3.20.2)
• Installing apeye (1.4.1)
• Installing autodocsumm (0.2.14)
• Installing cachecontrol (0.14.0)
• Installing dict2css (0.3.0.post1)
• Installing html5lib (1.1)
• Installing importlib-metadata (8.5.0)
• Installing mdit-py-plugins (0.4.2)
• Installing pdf2image (1.17.0)
• Installing pydata-sphinx-theme (0.15.4)
• Installing ruamel-yaml (0.18.6)
• Installing sphinx-autodoc-typehints (2.3.0)
• Installing sphinx-jinja2-compat (0.3.0)
• Installing sphinx-prompt (1.9.0)
• Installing sphinx-tabs (3.4.5)
• Installing ansys-sphinx-theme (1.2.0)
• Installing enum-tools (0.12.0)
• Installing jupytext (1.16.4)
• Installing nbsphinx (0.9.5)
• Installing numpydoc (1.8.0)
• Installing sphinx-design (0.6.1)
• Installing sphinx-notfound-page (1.0.4)
• Installing sphinx-copybutton (0.5.2)
• Installing sphinx-toolbox (3.8.1)

(CI run so cannot run pip freeze)

[RobPasMue]

Transferring to ansys-sphinx-theme..? If not, we can move it back. Can you confirm whether the local build works?

[Andy-Grigg]

Just tried this locally, and it also fails, so I think this is a theme issue as opposed to a CI issue:

Running Sphinx v8.1.3
C:\git\ansys\grantami-bomanalytics\doc\source\conf.py:114: SyntaxWarning: invalid escape sequence '\.'
  "^ansys\.grantami\.bomanalytics\.bom_types\._bom_types\.[\w]+\.[\w]+$"
'BUILD_EXAMPLES' environment variable is not set, using standalone examples.
loading translations [en]... done
making output directory... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
[autosummary] generating autosummary for: api\bom_builder\api.rst, api\bom_builder\builders.rst, api\bom_builder\helpers.rst, api\bom_builder\index.rst, api\bom_builder\schemas.rst, api\common.rst, api\compliance\bom.rst, api\compliance\index.rst, api\compliance\indicators.rst, api\compliance\materials.rst, ..., examples\1_Test_Example\1-1_Test_other_features.ipynb, examples\1_Test_Example\index.rst, examples\index.rst, getting_started\index.rst, index.rst, user_guide\batching.rst, user_guide\index.rst, user_guide\introduction.rst, user_guide\query_types.rst, user_guide\quick_code.rst
loading intersphinx inventory 'python' from https://docs.python.org/3.11/objects.inv ...
loading intersphinx inventory 'openapi-common' from https://openapi.docs.pyansys.com/version/stable/objects.inv ...
Writing evaluated template result to C:\git\ansys\grantami-bomanalytics\doc\_build\html\_static\nbsphinx-code-cells.css
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 36 source files that are out of date
updating environment: [new config] 36 added, 0 changed, 0 removed
reading sources... [100%] user_guide/quick_code
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying downloadable files... [100%] examples/1_Test_Example/1-1_Test_other_features.py
copying static files...
Writing evaluated template result to C:\git\ansys\grantami-bomanalytics\doc\_build\html\_static\basic.css
Writing evaluated template result to C:\git\ansys\grantami-bomanalytics\doc\_build\html\_static\documentation_options.js
Writing evaluated template result to C:\git\ansys\grantami-bomanalytics\doc\_build\html\_static\language_data.js
Writing evaluated template result to C:\git\ansys\grantami-bomanalytics\doc\_build\html\_static\copybutton.js
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
writing output... [100%] user_guide/quick_code
generating indices... genindex py-modindex done
copying linked files... [100%] examples\1_Test_Example\supporting-file.txt
copying notebooks ... [100%] examples/1_Test_Example/1-1_Test_other_features.ipynb
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done

Extension error (ansys_sphinx_theme.search.fuse_search):
Handler <function create_search_index at 0x0000020069555940> for event 'build-finished' threw an exception (exception: list index out of range)

[jorgepiloto]

Same issue in https://github.com/ansys/pydpf-core/actions/runs/11819743733/job/32930389290?pr=1846

[jorgepiloto]

I am suspicious about something going on within this function:

ansys-sphinx-theme/src/ansys_sphinx_theme/search/fuse_search.py

Lines 191 to 229 in e91ee99

	def create_search_index(app, exception):
	"""
	Generate search index at the end of the Sphinx build process.
	Parameters
	----------
	app : Sphinx
	Sphinx application instance.
	exception : Exception
	Exception raised during the build process, if any.
	"""
	if exception:
	return
	search_index_list = []
	static_search_options = app.config.html_theme_options.get("static_search", {})
	excluded_docs = static_search_options.get("files_to_exclude", [])
	included_docs = app.env.found_docs
	for exclude_doc in excluded_docs:
	exclude_doc = Path(exclude_doc).resolve()
	# Exclude documents based on whether exclude_doc is a folder or a file:
	# - For folders, exclude all documents within the folder.
	# - For files, exclude only the exact file match.
	included_docs = [
	doc for doc in included_docs if not Path(doc).resolve().is_relative_to(exclude_doc)
	]
	for document in included_docs:
	pattern = get_pattern_for_each_page(app, document)
	search_index = SearchIndex(document, app, pattern)
	search_index.build_sections()
	search_index_list.extend(search_index.indices)
	search_index_path = Path(app.builder.outdir) / "_static" / "search.json"
	with search_index_path.open("w", encoding="utf-8") as index_file:
	json.dump(search_index_list, index_file, ensure_ascii=False, indent=4)

[jorgepiloto]

However, this is strange since other libraries have migrated to v1.2.1 and have no issues. Even when the exclude_doc is not defined in their conf.py.

[Andy-Grigg]

This is certainly a strange issue. The PyGrantaJobQueue documentation builds file with the ^1.2 release, but bomanalytics and RecordLists fail. I can't think of any significant differences between these documentations.

[Revathyvenugopal162]

This is certainly a strange issue. The PyGrantaJobQueue documentation builds file with the ^1.2 release, but bomanalytics and RecordLists fail. I can't think of any significant differences between these documentations.

This issue occurred because of the grantami template used for the API reference, which we didn’t account for template parsing while creating json file. I’ve added the necessary changes in PR #586 and working in https://github.com/ansys/grantami-bomanalytics/actions/runs/11896275334/job/33148530429?pr=644

[Andy-Grigg]

I'm glad to see this works with the bomanalytics package, thank you for identifying the issue!

I did give this a go with our closed-source package as well though, and I now get the following error when building:

Extension error (ansys_sphinx_theme.search.fuse_search):
Handler <function create_search_index at 0x000001AEBFE0E520> for event 'build-finished' threw an exception (exception: 'list' object has no attribute 'split')

I'm guessing this function is related to the more powerful searching, which this closed-source package won't be using. Maybe this function can be wrapped in a broad exception handler that emits a warning if something goes wrong, and it's possible to just opt-out of running this function in the theme config? That way we'll be free to use this theme without worrying about these edge cases if we don't care about the more powerful cross-site searching.

[MaxJPRey]

This is certainly a strange issue. The PyGrantaJobQueue documentation builds file with the ^1.2 release, but bomanalytics and RecordLists fail. I can't think of any significant differences between these documentations.

This issue occurred because of the grantami template used for the API reference, which we didn’t account for template parsing while creating json file. I’ve added the necessary changes in PR #586 and working in https://github.com/ansys/grantami-bomanalytics/actions/runs/11896275334/job/33148530429?pr=644

Great catch @Revathyvenugopal162 .

[Revathyvenugopal162]

I'm glad to see this works with the bomanalytics package, thank you for identifying the issue!

I did give this a go with our closed-source package as well though, and I now get the following error when building:

Extension error (ansys_sphinx_theme.search.fuse_search):
Handler <function create_search_index at 0x000001AEBFE0E520> for event 'build-finished' threw an exception (exception: 'list' object has no attribute 'split')

I'm guessing this function is related to the more powerful searching, which this closed-source package won't be using. Maybe this function can be wrapped in a broad exception handler that emits a warning if something goes wrong, and it's possible to just opt-out of running this function in the theme config? That way we'll be free to use this theme without worrying about these edge cases if we don't care about the more powerful cross-site searching.

Thank you @Andy-Grigg for testing it! I am now checking if the title is a list or not to avoid the error mentioned above. Could you please test it again with the same branch? fix/search

[Andy-Grigg]

@Revathyvenugopal162 Thanks! I just tested again, and I can confirm that commit bff0e89 works as expected. No errors during the docs build, and local search works.

[Revathyvenugopal162]

@Revathyvenugopal162 Thanks! I just tested again, and I can confirm that commit bff0e89 works as expected. No errors during the docs build, and local search works.

Thanks for confirming @Andy-Grigg