Project fails to build with Sphinx 7.0.0 (jinja2.exceptions.UndefinedError: 'style' is undefined)

[Kwpolska]

Details

• Read the Docs project URL: https://readthedocs.org/projects/nikola/
• Build URL (if applicable): https://readthedocs.org/projects/nikola/builds/20338198/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/Kwpolska/

Expected Result

A successful build

Actual Result

The build failed:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/builders/html/__init__.py", line 1093, in handle_page
    output = self.templates.render(templatename, ctx)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/readthedocs_ext/readthedocs.py", line 185, in rtd_render
    content = old_render(template, render_context)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/jinja2glue.py", line 196, in render
    return self.environment.get_template(template).render(context)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/jinja2/environment.py", line 1301, in render
    self.environment.handle_exception()
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/themes/basic/page.html", line 10, in top-level template code
    {%- extends "layout.html" %}
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx_rtd_theme/layout.html", line 67, in top-level template code
    <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
jinja2.exceptions.UndefinedError: 'style' is undefined

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/cmd/build.py", line 285, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/application.py", line 351, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 294, in build_update
    self.build(to_build,
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 361, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 569, in write
    self._write_serial(sorted(docnames))
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 579, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/builders/html/__init__.py", line 667, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nikola/envs/latest/lib/python3.9/site-packages/sphinx/builders/html/__init__.py", line 1100, in handle_page
    raise ThemeError(__("An error happened in rendering the page %s.\nReason: %r") %
sphinx.errors.ThemeError: An error happened in rendering the page creating-a-site.
Reason: UndefinedError("'style' is undefined")

Theme error:
An error happened in rendering the page creating-a-site.
Reason: UndefinedError("'style' is undefined")

Our last successful build was 1.5 days ago, and it was built using Sphinx v6.2.1. The failed build is using Sphinx v7.0.0. (There were no doc changes between the two commits.)

[elParaguayo]

I do, generally, hate doing "+1" posts but I did want to say that I'm seeing exactly the same issue now: https://readthedocs.org/projects/qtile/builds/20338846/

[humitos]

Hi! Do your projects build locally (outside Read the Docs) using Sphinx 7.0.0?

[elParaguayo]

Thanks for the reply.

I get the same error when running locally. This is the end of the output when running make html:

writing output... [  1%] index
Theme error:
An error happened in rendering the page index.
Reason: UndefinedError("'style' is undefined")
make: *** [Makefile:47: html] Error 2

[Kwpolska]

My project builds correctly with Sphinx 7.0.0 when using the default Sphinx theme.

Trying to install the RTD theme downgrades Sphinx to 6.2.1. After forcing an install of 7.0.0 (with the error below), the RTD theme seems to be building correctly on my machine.

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
sphinx-rtd-theme 1.2.0 requires sphinx<7,>=1.6, but you have sphinx 7.0.0 which is incompatible.

[elParaguayo]

Ah. The issue for us seems to be the sphinx-rtd theme. It looks like it was using a very old version. Forcing it to use the latest makes the build succeed locally. Will try pushing and see if it also builds remotely.

[elParaguayo]

I can build locally with sphinx 7.0.0 and sphinx-rtd 1.2.0 but the build fails on the remote site because of the dependency conflict mentioned above:
https://readthedocs.org/projects/qtile/builds/20344495/

EDIT: unsurprisingly, pinning the remote build to sphinx<7.0.0 works.

[humitos]

OK, I see. It seems that Read the Docs Sphinx's theme is not compatible with Sphinx 7.x: https://github.com/readthedocs/sphinx_rtd_theme/blob/master/setup.cfg#L48

I'd suggest to pin Sphinx<7 for now until there is a new release for the theme.

[BeyondEvil]

I'm still seeing a pip error, despite sphinx<7.0.0:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
sphinx-rtd-theme 1.2.0 requires docutils<0.19, but you have docutils 0.19 which is incompatible.
Successfully installed docutils-0.19 importlib-metadata-6.6.0 zipp-3.15.0

.readthedocs.yaml

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

# Build from the docs/ directory with Sphinx
sphinx:
  configuration: docs/conf.py
  fail_on_warning: true

# Explicitly set the version of Python and its requirements
python:
  install:
    - requirements: docs/requirements.txt

requirements.in:
sphinx<7.0.0

requirements.txt

#
# This file is autogenerated by pip-compile with Python 3.9
# by the following command:
#
#    pip-compile --resolver=backtracking requirements.in
#
alabaster==0.7.13
    # via sphinx
babel==2.12.1
    # via sphinx
certifi==2023.5.7
    # via requests
charset-normalizer==3.1.0
    # via requests
docutils==0.19
    # via sphinx
idna==3.4
    # via requests
imagesize==1.4.1
    # via sphinx
importlib-metadata==6.6.0
    # via sphinx
jinja2==3.1.2
    # via sphinx
markupsafe==2.1.2
    # via jinja2
packaging==23.1
    # via sphinx
pygments==2.15.1
    # via sphinx
requests==2.30.0
    # via sphinx
snowballstemmer==2.2.0
    # via sphinx
sphinx==6.2.1
    # via -r requirements.in
sphinxcontrib-applehelp==1.0.4
    # via sphinx
sphinxcontrib-devhelp==1.0.2
    # via sphinx
sphinxcontrib-htmlhelp==2.0.1
    # via sphinx
sphinxcontrib-jsmath==1.0.1
    # via sphinx
sphinxcontrib-qthelp==1.0.3
    # via sphinx
sphinxcontrib-serializinghtml==1.1.5
    # via sphinx
urllib3==2.0.2
    # via requests
zipp==3.15.0
    # via importlib-metadata

[humitos]

@BeyondEvil your requirements.in should be like:

sphinx<7
sphinx_rtd_theme

That way it will take into consideration the constraints of the RTD Sphinx theme as well, which requires docutils<0.19.

[BeyondEvil]

Thanks!

I had added docsutils<0.19 to the .in-file but your was is much better. Didn't know you could do that.