When `sizes` is not specified with favicons the theme throws an error

[ns-rse]

Hi,

I've found my pages do not build with the recent release of pytdata-sphinx-theme-0.9.0 and fails with the following error...

[app] emitting event: 'build-finished'(ExtensionError("Handler <function update_templates at 0x7f689e710ee0> for event 'html-page-context'

Traceback (most recent call last):
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/pydata_sphinx_theme/__init__.py", line 155, in update_templates
    sizes=favicon["sizes"],
KeyError: 'sizes'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app.build(args.force_all, filenames)
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/application.py", line 330, in build
    self.builder.build_update()
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 286, in build_update
    self.build(to_build,
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 350, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 524, in write
    self._write_serial(sorted(docnames))
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 534, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/builders/html/__init__.py", line 625, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/builders/html/__init__.py", line 1026, in handle_page
    newtmpl = self.app.emit_firstresult('html-page-context', pagename,
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/application.py", line 457, in emit_firstresult
    return self.events.emit_firstresult(event, *args,
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/events.py", line 112, in emit_firstresult
    for result in self.emit(name, *args, allowed_exceptions=allowed_exceptions):
  File "/home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages/sphinx/events.py", line 102, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function update_templates at 0x7f689e710ee0> for event 'html-page-context' threw an exception (exception: 'sizes')

Extension error (pydata_sphinx_theme):
Handler <function update_templates at 0x7f689e710ee0> for event 'html-page-context' threw an exception (exception: 'sizes')

❱ pip show pydata-sphinx-theme
Name: pydata-sphinx-theme
Version: 0.9.0
Summary: Bootstrap-based Sphinx theme from the PyData community
Home-page: 
Author: 
Author-email: 
License: 
Location: /home/user/miniconda3/envs/pgfinder/lib/python3.9/site-packages
Requires: sphinx, packaging, docutils, beautifulsoup4
Required-by: 

[henilp105]

Respected sir, I have also faced the same error in the new 0.9.0 version. try falling back to 0.8.1 this will resolve the issues. @ns-rse this can be currently be resolved by using( pydata-sphinx-theme==0.8.1 ) in requirements.txt until a patch has not been submitted. Thanks and Regards, Henil Panchal

[ns-rse]

@henilp105 Thank you already pegged it to 0.8.1 in the GitHub action that builds my documentation GitHub pipeline.

[choldgraf]

The favicon documentation suggests that you need to provide a sizes keyword...are you not providing this? If not that explains the error. If so, then I think this is a bug

https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/configuring.html?highlight=favicon#adding-favicons

[ns-rse]

Thanks for looking at this @choldgraf

I have favicons defined but no size, currently with...

html_theme_options = {
    "show_nav_level": 2,
    "favicons": [
        {"rel": "icon", "href": "https://github.com/Mesnage-Org/pgfinder/actions/workflows/ci-tests.yml/badge.svg"},
        {"rel": "icon", "href": "https://codecov.io/gh/Mesnage-Org/pgfinder"},
    ],
}

...and building with pydata_sphinx_theme==0.9.0 fails as per above.

If however I add a size as you suggest...

html_theme_options = {
    "show_nav_level": 2,
    "favicons": [
        {
            "rel": "icon",
            "sizes": "156x20",
            "href": "https://github.com/Mesnage-Org/pgfinder/actions/workflows/ci-tests.yml/badge.svg",
        },
        {
            "rel": "icon",
            "sizes": "115x20",
            "href": "https://codecov.io/gh/Mesnage-Org/pgfinder",
        },
    ],
}

Then the documentation builds fine with pydata_sphinx_theme==0.9.0.

[choldgraf]

Next step

So I think this is not a bug per-se, but we could improve the UX by defining a default "size" in case the user doesn't present one.

[12rambau]

I was building favicon for my documentation and I remembered this issue. I just found this small favicon extention: https://pypi.org/project/sphinx-favicon/. Maybe instead of duplicate the work we could also have a look.

[choldgraf]

If that seems relatively well maintained, the functionality is there, and it's not a heavy dependency, I'd be +1 on just adding it as a dependency and using it for the favicon functionality