jinja2.exceptions.TemplateNotFound: toggle-primary-sidebar.html

[AlexanderJuestel]

Describe the bug

context
When I creating the the documentation page of GemGIS (https://gemgis.readthedocs.io/en/latest/), I have recently started to see an error: jinja2.exceptions.TemplateNotFound: toggle-primary-sidebar.html.

expectation
No error to occur

bug
The creating of the docs fails --> https://readthedocs.org/projects/gemgis/builds/20023049/

Reproduce the bug

The creating of the docs fails --> https://readthedocs.org/projects/gemgis/builds/20023049/

List your environment

No response

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[jayaddison]

Hi @AlexanderJuestel - the earliest failed build that I see with this error is from 2023-03-02: https://readthedocs.org/projects/gemgis/builds/19649141/

That looks like it's fairly soon after v1.0.0 of sphinx-book-theme was released (including some breaking changes, most likely).

Have you consulted the changelog for any relevant items?

[AlexanderJuestel]

@jayaddison Thanks for the hint! I will check out the changelog. A temporary solution could be to pin the book theme to an earlier version?

[jayaddison]

@AlexanderJuestel it could be, yep - if possible though, I'd recommend trying to find the relevant change that introduced the problem, and whether it's a bug/known-issue. If so, then it'll be easier to follow along and unpin the version (or to change this theme appropriately when ready to upgrade).

[AlexanderJuestel]

@jayaddison One thing that I could find right away is 60bcb7d#diff-d9e027334fa1c4b5093d44ff026f62f9e4d092fa735da8ffd1e6b96c0f645f3f

However, the changes made to https://github.com/sphinx-doc/sphinx/commits/master/sphinx/jinja2glue.py were not very revealing to me about what could have been broken.

[jayaddison]

Ok, thanks @AlexanderJuestel. The jinja2glue.py file seems to iterate through a series of template loaders (each with their own paths configured), and one of those should find and load the toggle-primary-sidebar.html file (that exists inside a components directory).

Currently I'm looking into the code here to try to figure out whether this additional file path is being considered at load-time:

sphinx-book-theme/src/sphinx_book_theme/__init__.py

Lines 191 to 198 in c2664dd

	def update_general_config(app):
	theme_dir = get_html_theme_path()
	# Update templates for sidebar. Needed for jupyter-book builds as jb
	# uses an instance of Sphinx class from sphinx.application to build the app.
	# The __init__ function of which calls self.config.init_values() just
	# before emitting `config-inited` event. The init_values function overwrites
	# templates_path variable.
	app.config.templates_path.append(os.path.join(theme_dir, "components"))

[AlexanderJuestel]

@jayaddison thanks for your efforts! I read somewhere else that it may be related to templates. Keep me updated if you find something.

[jayaddison]

A self-correction: I now believe that this is the relevant code to look at:

sphinx-book-theme/src/sphinx_book_theme/__init__.py

Lines 259 to 261 in c2664dd

	# Update templates for sidebar, for builds where config-inited is not called
	# (does not work in case of jupyter-book)
	app.config.templates_path.append(os.path.join(theme_dir, "components"))

Perhaps that additional entry in the template path list isn't being retained, for some reason.

[jayaddison]

Some more notes:

Dependency versions

• Downgrading sphinx-book-theme to v0.3.3 does allow gemgis documentation to build
• Building with v1.0.0 fails due to an unrelated error
• Building with v1.0.1 fails due to the error reported here

So there does appear to be an incompatibility related to v1.x that gemgis may need to address (or that may be a bug here).

Template origin

The sphinx-book-theme Sphinx theme depends upon (but does not inherit from?) pydata-sphinx-theme.

The toggle-primary-sidebar.html file is part of sphinx-book-theme.

But the error that appears in the build output seems to be in the context of pydata-sphinx-theme:

Extension error (pydata_sphinx_theme):
Handler <function update_and_remove_templates at 0x...> for event 'html-page-context' threw an exception (exception: toggle-primary-sidebar.html)

Why is that? Could there be a mismatch between the template search paths for the two themes?

[jayaddison]

The sphinx-book-theme Sphinx theme depends upon (but does not inherit from?) pydata-sphinx-theme.

Ok, sphinx-book-theme does in fact inherit from pydata-sphinx-theme:

sphinx-book-theme/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf

Line 2 in c2664dd

inherit = pydata_sphinx_theme

[jayaddison]

Sorry, @AlexanderJuestel - I've taken more of a look at this, but haven't been able to figure out what the root of the problem is. As you suggest, limiting the sphinx-book-theme version (to <1.0.0, or ==0.3.3, for example) should provide a workaround.

[AlexanderJuestel]

@jayaddison thanks for checking, I will try limiting the version and get back to you ASAP