search

readthedocs / sphinx_rtd_theme

Sphinx theme from Read the Docs
https://sphinx-rtd-theme.readthedocs.io/
MIT License
4.75k stars 1.73k forks source link

UndefinedError("'style' is undefined") #1571

Closed douglas-raillard-arm closed 1 month ago

douglas-raillard-arm commented 2 months ago

Problem

Doc builds with sphinx-rtd-theme seems to have stopped working in our CI. I cannot reproduce locally unfortunately, even with the same Python version (but not same distro version).

Reproducible Project

Project: https://gitlab.arm.com/tooling/lisa I could not manage to reproduce the issue outside our CI, but the doc build can be achieved with:

git clone https://git.gitlab.arm.com/tooling/lisa.git
# This will be taken into account when the venv is created. A python3.11 binary needs to exist in the PATH.
export LISA_PYTHON=python3.11
cd lisa
# This will create a venv
source init_env
# Build the doc under ./doc/_build
lisa-doc-build

Error Logs/Results

This started failing this week out of the blue: https://gitlab.arm.com/tooling/lisa/-/jobs/70959

reading sources... [ 75%] misc_utilities .. workflows/automated_testing
reading sources... [100%] workflows/index .. workloads
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
Traceback (most recent call last):
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/builders/html/__init__.py", line 1119, in handle_page
    output = self.templates.render(templatename, ctx)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/jinja2glue.py", line 200, in render
    return self.environment.get_template(template).render(context)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/jinja2/environment.py", line 1304, in render
    self.environment.handle_exception()
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/jinja2/environment.py", line 939, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/themes/basic/page.html", line 10, in top-level template code
    {%- extends "layout.html" %}
    ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx_rtd_theme/layout.html", line 23, 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/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/cmd/build.py", line 337, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/application.py", line 351, in build
    self.builder.build_update()
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 293, in build_update
    self.build(to_build,
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 362, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 567, in write
    self._write_parallel(sorted(docnames),
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 594, in _write_parallel
    self.write_doc(firstname, doctree)
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/builders/html/__init__.py", line 665, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx/builders/html/__init__.py", line 1126, 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 bisector/api.
Reason: UndefinedError("'style' is undefined")
Theme error:
An error happened in rendering the page bisector/api.
Reason: UndefinedError("'style' is undefined")

Expected Results

The doc should build successfully

Environment Info

geo-martino commented 2 months ago

Second this. Receiving the exact same error out of almost nowhere when building pages on this repo here: https://github.com/geo-martino/musify.

Can be replicated by cloning the repo, installing the docs optional dependencies via pip install .[docs] and running make rebuild-html.

Logs here: https://github.com/geo-martino/musify/actions/runs/10099215047/job/27927927658

zaufi commented 2 months ago

Also hit this error w/ Sphinx 8.0.0 (also tried 7.4.7, 7.2.6) and sphinx_rtd_theme

humitos commented 2 months ago

Taking a look at the description of the issue I can say from this error line that the style variable is not present in the HTML context for Jinja.

  File "/home/ubuntu/builds/iyA2D7ai/0/tooling/lisa/tmp/tmp.0VAnEEbH4h-worktree/.lisa-venv-3.11/lib/python3.11/site-packages/sphinx_rtd_theme/layout.html", line 23, in top-level template code
    <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />

I tried using Sphinx 8 in https://github.com/readthedocs/sphinx_rtd_theme/pull/1576 and all the tests run without issues. We will need a a minimal reproducible example that triggers this issue to be able to reproduce it.

zaufi commented 2 months ago

Also hit this error w/ Sphinx 8.0.0 (also tried 7.4.7, 7.2.6) and sphinx_rtd_theme

Reproduced in my pipeline w/ Sphinx 8.0.2: https://github.com/zaufi/pytest-matcher/actions/runs/10182227565/job/28164231159#step:9:46

humitos commented 2 months ago

@zaufi can you provide a minimal reproducible example (including the step by step commands to run) that I can run in my local instance so I can debug it in deep?

zaufi commented 2 months ago

@zaufi can you provide a minimal reproducible example (including the step by step commands to run) that I can run in my local instance so I can debug it in deep?

Just tried to make a trivial project inside a test venv and I've failed to reproduce it even copying the config and some RST files out of my project.

But it 100% reproducible w/ my pet project in 3 steps:

$ git clone https://github.com/zaufi/pytest-matcher.git
Cloning into 'pytest-matcher'...
remote: Enumerating objects: 1100, done.
remote: Counting objects: 100% (404/404), done.
remote: Compressing objects: 100% (126/126), done.
remote: Total 1100 (delta 307), reused 352 (delta 274), pack-reused 696
Receiving objects: 100% (1100/1100), 315.09 KiB | 766.00 KiB/s, done.
Resolving deltas: 100% (602/602), done.

$ cd pytest-matcher/

$ hatch run doc:build
Running Sphinx v8.0.2
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 7 source files that are out of date
updating environment: [new config] 7 added, 0 changed, 0 removed
reading sources... [100%] latest-changelog
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying static files... done
copying extra files... done
copying assets: done

Theme error:
An error happened in rendering the page api.
Reason: UndefinedError("'style' is undefined")

Where the doc:build is an alias for sphinx-build --color -j auto doc/ build/sphinx/html/. So, for example to add -v or other agrs you can use:

$ hatch run doc:sphinx-build -vv --color -j auto doc/ build/sphinx/html/
…
Traceback (most recent call last):
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 1160, in handle_page
    output = self.templates.render(templatename, ctx)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/jinja2glue.py", line 201, in render
    return self.environment.get_template(template).render(context)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/jinja2/environment.py", line 1304, in render
    self.environment.handle_exception()
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/jinja2/environment.py", line 939, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/themes/basic/page.html", line 10, in top-level template code
    {%- extends "layout.html" %}
    ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx_rtd_theme/layout.html", line 23, 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/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/cmd/build.py", line 337, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/application.py", line 378, in build
    self.builder.build_update()
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 296, in build_update
    self.build(to_build,
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 366, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 610, in write
    self._write_parallel(sorted(docnames),
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 637, in _write_parallel
    self.write_doc(firstname, doctree)
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 675, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/home/exher/tmp/pytest-matcher/.venv/doc/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 1167, 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 api.
Reason: UndefinedError("'style' is undefined")

Theme error:
An error happened in rendering the page api.
Reason: UndefinedError("'style' is undefined")
humitos commented 1 month ago

Thanks @zaufi for sharing those steps.

I was able to find the issue. The style variable was removed from the html_context and it's not passed anymore to Jinja templates. That's why it's failing. It was removed in this PR https://github.com/sphinx-doc/sphinx/pull/11381.

However, we adapted our code already for that change and it should be working fine. Make sure you are installing the latest stable version of our theme, 2.0.0

If that doesn't work, please use our latest 2.1.0rc1 and let us know if that solves the issue. Thanks.

zaufi commented 1 month ago

Requiring sphinx < 8.0 and sphinx_rtd_theme >= 2.0 makes it work again.

Thank you!

njzjz commented 1 month ago

I got this error when sphinx==8.0.0 and sphinx-rtd-theme==0.5.1 were installed. Pining sphinx-rtd-theme to >=0.6 gives me the correct sphinx and sphinx-rtd-theme versions.

humitos commented 1 month ago

I'm closing this issue since it's not a problem in the latest versions of the theme. The problem comes from installing an older version of our theme with a newer version of Sphinx.