Read the Docs build fails

[stevepiercy]

The Read the Docs build fails with the following error message.

https://readthedocs.org/projects/pydata-sphinx-theme/builds/26913127/

---

Error

The sphinx.configuration key is missing. This key is now required, see our blog post for more information.

---

I don't see any build.commands in your readthedocs.yml, assuming that is the file you use and have configured in your RTD project. The default is .readthedocs.yaml. I think the fix would be to insert this snippet, immediately before the python: stanza.

sphinx:
  # Path to your Sphinx configuration file.
  configuration: docs/conf.py

I filed an issue for a similar incident on Jan 6, 2025, but I use build.commands so it doesn't affect my projects. Y'all have a different configuration, and I am not entirely sure what is its intent, based on the RTD docs.

https://docs.readthedocs.io/en/stable/config-file/index.html

Can you investigate and verify the core issue and whether this would be a correct fix? I can file a PR, too.

[drammock]

@stevepiercy I was expecting periodic doc build failures this month due to a deprecation in RTD. I started to address it weeks ago in #2083 but got stuck getting playwright to install properly (#2083 (comment)). If you have any insight on how to get that unblocked, it would be much appreciated!

[stevepiercy]

@drammock it looks like you got over one hurdle, and are now playing whack a mole with warnings as errors. Should I close this issue, or will you handle that?

If you want to pass in suppress_warnings to your production build, I've done that in other projects where the Pygments highlighter is less than perfect for some languages.

SPHINXOPTS      ?=
SPHINXBUILD     = "$(realpath venv/bin/sphinx-build)"
DOCS_DIR        = ./docs/
BUILDDIR        = ../_build
PAPEROPT_a4     = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: rtd-pr-preview
rtd-pr-preview:  ## Build pull request preview on Read the Docs
<snip>
	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/

make SPHINXOPTS="-D suppress_warnings='misc.highlighting_failure'" rtd-pr-preview

Please let me know. Thank you!

[drammock]

this will now auto-close when #2083 is merged.

Thanks for the suggestion about suppress_warnings... I considered it but it feels a little to coarse-grained for my taste, as there's really only a few very specific warnings we want to tolerate, not "all warnings of type T"