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 https://github.com/NREL/floris/pull/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 https://github.com/executablebooks/sphinx-book-theme/issues/729.

[adam-grant-hendry]

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