incompatible with readthedocs builds and fail_on_warning option

[chrisjsewell]

Heya,

This theme causes readthedocs to emit a warning, meaning that https://docs.readthedocs.io/en/stable/config-file/v2.html#sphinx-fail-on-warning will always fail (and this also means that it is not possible to properly use https://docs.readthedocs.io/en/stable/pull-requests.html)

You can see this in your own docs builds: https://readthedocs.org/projects/sphinx-immaterial/builds/21647542/

WARNING: Missing searchtools: /home/docs/checkouts/readthedocs.org/user_builds/sphinx-immaterial/checkouts/stable/_readthedocs/html/_static/searchtools.js

[2bndy5]

Actually, I think this warning comes from the RTD sphinx extension (mandated to add the version drop down info). It could be argued that the RTD sphinx extension shouldn't assume the Sphinx basic theme's assets are present.

We could specifically not exclude that file when RTD env is detected

sphinx-immaterial/sphinx_immaterial/__init__.py

Lines 61 to 85 in c61bad9

	def init_js_files(self):
	super().init_js_files()
	# Remove unnecessary scripts
	excluded_scripts = set(
	[
	"_static/underscore.js",
	"_static/doctools.js",
	"_static/language_data.js",
	"_static/documentation_options.js",
	"_static/sphinx_highlight.js",
	]
	)
	if nav_adapt.READTHEDOCS is None:
	excluded_scripts.add("_static/jquery.js")
	excluded_scripts.add("_static/_sphinx_javascript_frameworks_compat.js")
	if version_info < (7, 2):
	self.script_files: List[sphinx.builders.html.JavaScript] = [
	x for x in self.script_files if x.filename not in excluded_scripts
	]
	else:
	self._js_files: List[sphinx.builders.html._assets._JavaScript] = [ # type: ignore[name-defined]
	x for x in self._js_files if x.filename not in excluded_scripts
	]

but IDK if that will have a conflict with the actual JS files being used.

[chrisjsewell]

Thanks for the quick response @2bndy5 .

Firstly, it would be good to clarify if this is actually breaking anything in the RTD builds?

Next, I think a minimal "fix" could be to ask the RTD guys to change this line: https://github.com/readthedocs/readthedocs-sphinx-ext/blob/7c60d1646c12ac0b83d61abfbdd5bcd77d324124/readthedocs_ext/readthedocs.py#L273

to something like

        log.warning('Missing searchtools: {}'.format(searchtools_file), type="readthedocs", subtype="searchtools")

this way one could at least use https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings, to ignore the warning (and you could document that here)

[2bndy5]

Firstly, it would be good to clarify if this is actually breaking anything in the RTD builds?

The only thing I can think of is the RTD search feature scoped to the entire RTD project (all builds not just an individual build).

Next, I think a minimal fix could be to ask the RTD guys to change ...

I will escalate this as it does seem like they're very responsive. We might even get a better answer to the first question.

[2bndy5]

This problem was resolved upstream.