deprecate favicons

Author: 12rambau

docs/user_guide/branding.rst

@@ -112,6 +112,10 @@ Add favicons
 
 ``pydata_sphinx_theme`` supports the `standard sphinx favicon configuration <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_favicon>`_, using ``html_favicon``.
 
+.. warning::
+
+   The support for complex and multiple favicons will be dropped in version 0.15. Instead you can use the `sphinx-favicon <https://sphinx-favicon.readthedocs.io/en/stable/>`__ extention that provide the same functionalities using more flexible parameters.
+
 Additionally you may add any number of browser- or device-specific favicons of any size.
 To do so, use the ``html_theme_options["favicons"]`` configuration key.
 The only required argument is ``href``, which can be either an absolute URL (beginning with ``http``) or a local path relative to your ``html_static_path``.

src/pydata_sphinx_theme/__init__.py

@@ -32,6 +32,14 @@
 def update_config(app):
     theme_options = app.config.html_theme_options
 
+    # DEPRECATE >= v0.15
+    if theme_options.get("favicons"):
+        logger.warning(
+            "Deprecated config `favicons` used."
+            "The favicon configuration have been droped in favor of the sphinx-favicon extention."
+            "Please see their documentation for more information."
+        )
+
     # DEPRECATE >= v0.10
     if theme_options.get("search_bar_position") == "navbar":
         logger.warning(

tests/sites/deprecated/conf.py

@@ -28,6 +28,23 @@
         "edit-this-page.html",
         "sourcelink.html",
     ],
+    "favicons": [
+        {
+            "rel": "icon",
+            "sizes": "16x16",
+            "href": "https://secure.example.com/favicon/favicon-16x16.png",
+        },
+        {
+            "rel": "icon",
+            "sizes": "32x32",
+            "href": "favicon-32x32.png",
+        },
+        {
+            "rel": "apple-touch-icon",
+            "sizes": "180x180",
+            "href": "apple-touch-icon-180x180.png",
+        },
+    ],
 }
 
 html_sidebars = {"section1/index": ["sidebar-nav-bs.html"]}

tests/test_build.py

@@ -235,50 +235,6 @@ def test_logo_external_image(sphinx_build_factory):
     assert f'src="{test_url}"' in index_str
 
 
-def test_favicons(sphinx_build_factory):
-    """Test that arbitrary favicons are included."""
-    html_theme_options_favicons = {
-        "favicons": [
-            {
-                "rel": "icon",
-                "sizes": "16x16",
-                "href": "https://secure.example.com/favicon/favicon-16x16.png",
-            },
-            {
-                "rel": "icon",
-                "sizes": "32x32",
-                "href": "favicon-32x32.png",
-            },
-            {
-                "rel": "apple-touch-icon",
-                "sizes": "180x180",
-                "href": "apple-touch-icon-180x180.png",
-            },
-        ]
-    }
-    confoverrides = {"html_theme_options": html_theme_options_favicons}
-    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
-
-    index_html = sphinx_build.html_tree("index.html")
-
-    icon_16 = (
-        '<link href="https://secure.example.com/favicon/favicon-16x16.png" '
-        'rel="icon" sizes="16x16" type="image/png"/>'
-    )
-    icon_32 = (
-        '<link href="_static/favicon-32x32.png" rel="icon" sizes="32x32" '
-        'type="image/png"/>'
-    )
-    icon_180 = (
-        '<link href="_static/apple-touch-icon-180x180.png" '
-        'rel="apple-touch-icon" sizes="180x180" type="image/png"/>'
-    )
-    print(index_html.select("head")[0])
-    assert icon_16 in str(index_html.select("head")[0])
-    assert icon_32 in str(index_html.select("head")[0])
-    assert icon_180 in str(index_html.select("head")[0])
-
-
 def test_navbar_align_default(sphinx_build_factory):
     """The navbar items align with the proper part of the page."""
     sphinx_build = sphinx_build_factory("base").build()
@@ -755,7 +711,7 @@ def test_deprecated_build_html(sphinx_build_factory, file_regression):
 
     # check the deprecation warnings
     warnings = sphinx_build.warnings.split("WARNING: ")
-    assert len(warnings) == 5  # testing the text of the warning is not necessary here
+    assert len(warnings) == 6  # testing the text of the warning is not necessary here
 
     index_html = sphinx_build.html_tree("index.html")
     subpage_html = sphinx_build.html_tree("section1/index.html")
@@ -770,6 +726,14 @@ def test_deprecated_build_html(sphinx_build_factory, file_regression):
         sidebar.prettify(), basename="sidebar_subpage", extension=".html"
     )
 
+    # the favicons
+    icon_16 = '<link href="https://secure.example.com/favicon/favicon-16x16.png" rel="icon" sizes="16x16" type="image/png"/>'  # fmt: skip
+    assert icon_16 in str(index_html.select("head")[0])
+    icon_32 = '<link href="_static/favicon-32x32.png" rel="icon" sizes="32x32" type="image/png"/>'  # fmt: skip
+    assert icon_32 in str(index_html.select("head")[0])
+    icon_180 = '<link href="_static/apple-touch-icon-180x180.png" rel="apple-touch-icon" sizes="180x180" type="image/png"/>'  # fmt: skip
+    assert icon_180 in str(index_html.select("head")[0])
+
     # Secondary sidebar should not have in-page TOC if it is empty
     assert not sphinx_build.html_tree("page1.html").select("div.onthispage")