Jupyter Book version bug with custom templates

[rafmudaf]

Jupyter Book latest version fails with custom templates

We use custom templates to compile the API documentation recursively for classes and modules through the _templates directory. This idea was taken from this SO post and incorporated in #514.

Jupyter Book versions greater than 0.13.3 break with this error:

Extension error (pydata_sphinx_theme):
Handler <function update_and_remove_templates at 0x7fdfb0437280> for event 'html-page-context' threw an exception (exception: toggle-primary-sidebar.html)
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.8.16/x64/lib/python3.8/site-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
  File "/opt/hostedtoolcache/Python/3.8.16/x64/lib/python3.8/site-packages/pydata_sphinx_theme/__init__.py", line 241, in update_and_remove_templates
    context[section] = list(filter(_remove_empty_templates, context[section]))
  File "/opt/hostedtoolcache/Python/3.8.16/x64/lib/python3.8/site-packages/pydata_sphinx_theme/__init__.py", line 236, in _remove_empty_templates
    rendered = app.builder.templates.render(tname, context)
  File "/opt/hostedtoolcache/Python/3.8.16/x64/lib/python3.8/site-packages/sphinx/jinja2glue.py", line 189, in render
    return self.environment.get_template(template).render(context)
  File "/opt/hostedtoolcache/Python/3.8.16/x64/lib/python3.8/site-packages/jinja2/environment.py", line 1010, in get_template
    return self._load_template(name, globals)
  File "/opt/hostedtoolcache/Python/3.8.16/x64/lib/python3.8/site-packages/jinja2/environment.py", line 969, in _load_template
    template = self.loader.load(self, name, self.make_globals(globals))
  File "/opt/hostedtoolcache/Python/3.8.16/x64/lib/python3.8/site-packages/jinja2/loaders.py", line 126, in load
    source, filename, uptodate = self.get_source(environment, name)
  File "/opt/hostedtoolcache/Python/3.8.16/x64/lib/python3.8/site-packages/sphinx/jinja2glue.py", line 210, in get_source
    raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: toggle-primary-sidebar.html

The bug seems to be described here and fixed here, but then it is again mentioned in a couple of other issues here and here.

Ultimately, this should be addressed one way or another in order to keep up with Jupyter Book and subsequent dependencies like the PyData Sphinx Theme.

How to reproduce

Build the documentation with Jupyter Book greater than version 0.13.3.

[TomaSusi]

Just ran into this issue. Downgrading is not a great solution.

[rafmudaf]

Just ran into this issue. Downgrading is not a great solution.

@TomaSusi just a heads up that this repository is not related to Jupyter Book, though we do use it for our documentation. Your message will get more eyes from the people working on this bug if you post in an issue such as executablebooks/sphinx-book-theme#729.

[adam-grant-hendry]

See the root cause analysis in pydata-sphinx-theme #1511 and the corresponding fix in sphinx-book-theme PR #770.

[misi9170]

@rafmudaf does #853, and in particular, the move away from custom templates, solve this issue for us? If so, should we close the issue?

[rafmudaf]

I'm not sure. The docs should be built with Jupyter Book version greater than 0.13.3 to verify. In the issue description, the docs don't build at all, so if they build and look correct with the latest version then I think it's resolved.

[paulf81]

I built with v1.x, that is also what is used in the github actions

[rafmudaf]

Great, then it sounds like this one is fixed.