Option toc_hover=False raises Theme error

[lneuhaus]

When I use this theme with toc_hover=False, I get the following error

Theme error:
An error happened in rendering the page _autosummary/[filename]
Reason: UndefinedError("'dropdown_link' is undefined")
make: *** [Makefile:60: html] Error 2

Searching for dropdown_link in this repo shows that this variable is only conditionally defined in the template.

[Mandrenkov]

Hey @lneuhaus, I'm having some trouble reproducing this issue on my end.

Do you mind sharing a relevant snippet from your conf.py file?

[josh146]

Here is the relevant code:

xanadu-sphinx-theme/xanadu_sphinx_theme/header.html

Lines 43 to 50 in dc85686

	{% if use_hover_toc and theme_navbar_left_links|length != 0 %}
	{# Extract active navbar entries #}
	{% set dropdown_link = theme_navbar_left_links|selectattr("active") | map(attribute="name") | list %}
	{% endif %}
	{% if use_hover_toc and dropdown_link|length == 0 %}
	{# The project wordmark provides a hover TOC #}
	{{ hover_toc(wordmark(), pathto(theme_navbar_home_link, 1), "navbar-brand") }}

@lneuhaus has found an edge case/bug where use_hover_toc=True but there are 0 navbar left links. From chatting to him, he solved this locally by simply adding more navbar links.

But this can also be fixed by adding in

{% set dropdown_link = [] %}

above line 43

[Mandrenkov]

That's interesting - I was trying to build the Xanadu Sphinx Theme docs locally with

html_theme_options = {
    # ...
    "navbar_left_links": [],
    # ...
    "toc_global": False,
    "toc_hover": True,
    # ...
}

to reproduce the issue but the build succeeded

$ grep -E "toc_(g|h)|left" doc/conf.py
    "navbar_left_links": [],
    "toc_global": False,
    "toc_hover": True,
$ make docs
make -C doc html
Running Sphinx v4.5.0
making output directory... done
[autosummary] generating autosummary for: code.rst, configuration.rst, directives.rst, elements.rst, gallery.rst, gallery/index.rst, gallery/sg_execution_times.rst, gallery/tutorial_demo.rst, index.rst, release_notes.rst, started.rst
[autosummary] generating autosummary for: /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.rst
[autosummary] generating autosummary for: /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.BioDirective.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.CommunityCardDirective.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.DetailsDirective.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.GalleryItemDirective.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.IndexCardDirective.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.Path.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.RelatedDemoDirective.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.TitleCardDirective.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.YouTubeVideoDirective.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.files.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.setup.rst, /Users/mikhail/ro/xanadu-sphinx-theme/doc/api/xanadu_sphinx_theme.templates_dir.rst
generating gallery...
WARNING: 'pypandoc' not available. Using Sphinx-Gallery to convert rst text blocks to markdown for .ipynb files.
generating gallery for gallery... [100%] tutorial_demo.py
computation time summary:
    - tutorials/tutorial_demo.py:   0.00 sec   0.0 MB
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 24 added, 0 changed, 0 removed
reading sources... [100%] started
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] started
generating indices... genindex py-modindex done
highlighting module code... [100%] xanadu_sphinx_theme.directives.youtube_video
writing additional pages... search done
copying images... [100%] gallery/images/thumb/sphx_glr_tutorial_demo_thumb.png
copying downloadable files... [100%] gallery/tutorial_demo.ipynb
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in _build/html.

Sphinx-Gallery successfully executed 0 out of 0 files subselected by:

    gallery_conf["filename_pattern"] = 'tutorial'
    gallery_conf["ignore_pattern"]   = '__init__\\.py'

after excluding 1 file that had previously been run (based on MD5).

embedding documentation hyperlinks...
embedding documentation hyperlinks for gallery... [100%] tutorial_demo.html

[josh146]

Oh weird - maybe different versions of Jinja? Only thing I can think of 🤔

[Mandrenkov]

Could be! Here are my packages:

$ pip list
Package                       Version     Editable project location
----------------------------- ----------- -------------------------------------
alabaster                     0.7.12
astroid                       2.11.7
Babel                         2.10.3
black                         22.3.0
build                         0.7.0
certifi                       2022.6.15.1
charset-normalizer            2.1.1
click                         8.1.3
colorama                      0.4.6
cycler                        0.11.0
dill                          0.3.6
docutils                      0.17.1
fonttools                     4.37.1
idna                          3.3
imagesize                     1.4.1
importlib-metadata            4.12.0
importlib-resources           5.9.0
isort                         5.10.1
Jinja2                        3.1.2
kiwisolver                    1.4.4
lazy-object-proxy             1.9.0
m2r2                          0.3.2
MarkupSafe                    2.1.1
matplotlib                    3.5.3
mccabe                        0.7.0
mistune                       0.8.4
mypy-extensions               0.4.3
numpy                         1.23.3
packaging                     21.3
pathspec                      0.10.3
pep517                        0.13.0
Pillow                        9.3.0
pip                           22.3.1
platformdirs                  2.6.2
Pygments                      2.13.0
pylint                        2.13.7
pyparsing                     3.0.9
python-dateutil               2.8.2
pytz                          2022.2.1
requests                      2.28.1
setuptools                    58.1.0
six                           1.16.0
snowballstemmer               2.2.0
Sphinx                        4.5.0
sphinx-copybutton             0.5.0
sphinx-gallery                0.10.1
sphinxcontrib-applehelp       1.0.2
sphinxcontrib-devhelp         1.0.2
sphinxcontrib-htmlhelp        2.0.0
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          1.0.3
sphinxcontrib-serializinghtml 1.1.5
tomli                         2.0.1
typing_extensions             4.4.0
urllib3                       1.26.12
wheel                         0.38.1
wrapt                         1.14.1
xanadu-sphinx-theme           0.3.6       /Users/mikhail/ro/xanadu-sphinx-theme
zipp                          3.8.1

[lneuhaus]

I was definitely using an older jinja version:

Jinja2                               3.0.0
jinja2-time                          0.2.0

But I tried to reproduce the issue with a clone of this repo in the doc folder, and was also unable to do that. So the issue must be somewhere else. But also I don't see how the template can not break with the current version.

[lneuhaus]

Maybe best to blame this on a broken environment on my end and not change the code.

[Mandrenkov]

@lneuhaus, do you mind upgrading Jinja2 to the latest version in your repository and checking if the error still happens?

[lneuhaus]

I tried this with Jinja2 3.1.2, and it works. However (and this is the reason I didn't upgrade Jinja in the first place), there seems to be a bug with nbsphinx which disappears when I move back to Jinja2 3.0.0 (so I have to disable that extension to get a successful build. So I'd say there is still a bug in this repo, but it could also be solved by pinning Jinja2>=3.1.2 (or maybe slightly lower versions).

In case you're curious about the nbsphinx issue:

Extension error:
Could not import extension nbsphinx (exception: cannot import name 'contextfilter' from 'jinja2' (/home/leo/.conda/envs/xanadu/lib/python3.9/site-packages/jinja2/__init__.py))
make: *** [Makefile:60: html] Error 2

[lneuhaus]

For reference spatialaudio/nbsphinx#710

[lneuhaus]

jupyter/nbconvert#1742 (comment). I think we can close this, unless you want to be explicit in pinning the Jinja2 version dependency here.

[Mandrenkov]

Thanks for the investigation, @lneuhaus! I think the best course of action is to define dropdown_link as @josh146 suggested above - it seems like a small price to pay to maintain project compatibility (especially because I'm not sure if any upstream repositories which use this theme rely on Jinja2 < 3.1.2 behaviour).

[Mandrenkov]

This issue has been fixed in v0.3.7 of the Xanadu Sphinx Theme.