fix: deprecate use of the favicon config parameter (#1225)

Co-authored-by: Chris Holdgraf <[email protected]>

docs/conf.py

@@ -1,6 +1,7 @@
 # -- Path setup --------------------------------------------------------------
 import os
 import sys
+import pydata_sphinx_theme
 
 sys.path.append("scripts")
 from gallery_directive import GalleryDirective
@@ -11,9 +12,6 @@
 copyright = "2019, PyData Community"
 author = "PyData Community"
 
-import pydata_sphinx_theme
-
-
 # -- General configuration ---------------------------------------------------
 
 extensions = [
@@ -33,41 +31,55 @@
     # "nbsphinx",  # Uncomment and comment-out MyST-NB for local testing purposes.
     "numpydoc",
     "sphinx_togglebutton",
+    "sphinx_favicon",
 ]
 
-# -- Internationalization ------------------------------------------------
-# specifying the natural language populates some key tags
-language = "en"
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+
+# -- Sitemap -----------------------------------------------------------------
 
 # ReadTheDocs has its own way of generating sitemaps, etc.
 if not os.environ.get("READTHEDOCS"):
     extensions += ["sphinx_sitemap"]
 
-    # -- Sitemap -------------------------------------------------------------
     html_baseurl = os.environ.get("SITEMAP_URL_BASE", "http://127.0.0.1:8000/")
     sitemap_locales = [None]
     sitemap_url_scheme = "{link}"
 
+
+# -- autosummary -------------------------------------------------------------
+
 autosummary_generate = True
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+# -- Internationalization ----------------------------------------------------
 
-# -- Extension options -------------------------------------------------------
+# specifying the natural language populates some key tags
+language = "en"
+
+# -- MyST options ------------------------------------------------------------
 
 # This allows us to use ::: to denote directives, useful for admonitions
 myst_enable_extensions = ["colon_fence", "linkify", "substitution"]
+myst_heading_anchors = 2
+myst_substitutions = {"rtd": "[Read the Docs](https://readthedocs.org/)"}
+
+# -- Ablog options -----------------------------------------------------------
+
+blog_path = "examples/blog/index"
+blog_authors = {
+    "pydata": ("PyData", "https://pydata.org"),
+    "jupyter": ("Jupyter", "https://jupyter.org"),
+}
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = "pydata_sphinx_theme"
 html_logo = "_static/logo.svg"
 html_favicon = "_static/logo.svg"
@@ -168,9 +180,6 @@
     ],
 }
 
-myst_heading_anchors = 2
-myst_substitutions = {"rtd": "[Read the Docs](https://readthedocs.org/)"}
-
 html_context = {
     "github_user": "pydata",
     "github_repo": "pydata-sphinx-theme",
@@ -182,22 +191,35 @@
     "contributing.rst": "community/index.rst",
 }
 
-# ABlog configuration
-blog_path = "examples/blog/index"
-blog_authors = {
-    "pydata": ("PyData", "https://pydata.org"),
-    "jupyter": ("Jupyter", "https://jupyter.org"),
-}
-
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
 todo_include_todos = True
 
+# -- favicon options ---------------------------------------------------------
+
+# see https://sphinx-favicon.readthedocs.io for more information about the
+# sphinx-favicon extention
+favicons = [
+    # generic icons compatible with most browsers
+    "favicon-32x32.png",
+    "favicon-16x16.png",
+    {"rel": "shortcut icon", "sizes": "any", "href": "favicon.ico"},
+    # chrome specific
+    "android-chrome-192x192.png",
+    # apple icons
+    {"rel": "mask-icon", "color": "#459db9", "href": "safari-pinned-tab.svg"},
+    {"rel": "apple-touch-icon", "href": "apple-touch-icon.png"},
+    # msapplications
+    {"name": "msapplication-TileColor", "content": "#459db9"},
+    {"name": "theme-color", "content": "#ffffff"},
+    {"name": "msapplication-TileImage", "content": "mstile-150x150.png"},
+]
+
+# -- application setup -------------------------------------------------------
+
 
 def setup(app):
-    # Add the gallery directive
     app.add_directive("gallery-grid", GalleryDirective)

docs/user_guide/branding.rst

@@ -113,6 +113,11 @@ This will appear just after your logo image if it is set.
 Add favicons
 ============
 
+.. deprecated:: 0.15
+
+   Support for complex and multiple favicons will be dropped in version 0.15. Instead use the `sphinx-favicon <https://sphinx-favicon.readthedocs.io/en/stable/>`__ extension. It provides the same functionality using more flexible parameters.
+
+
 ``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``.
 
 Additionally you may add any number of browser- or device-specific favicons of any size.

pyproject.toml

@@ -69,6 +69,7 @@ doc = [
   "sphinx-design",
   "sphinx-togglebutton",
   "sphinxcontrib-youtube",
+  "sphinx-favicon>=1.0.1",
   # Install nbsphinx in case we want to test it locally even though we can't load
   # it at the same time as MyST-NB.
   "nbsphinx",

src/pydata_sphinx_theme/__init__.py

@@ -80,13 +80,20 @@ def update_config(app):
             "Use `secondary_sidebar_items`."
         )
 
-    # DEPRECATE after 0.14
+    # TODO: DEPRECATE after 0.14
     if theme_options.get("footer_items"):
         theme_options["footer_start"] = theme_options.get("footer_items")
         logger.warning(
             "`footer_items` is deprecated. Use `footer_start` or `footer_end` instead."
         )
 
+    # TODO: DEPRECATE after v0.15
+    if theme_options.get("favicons"):
+        logger.warning(
+            "The configuration `favicons` is deprecated."
+            "Use the sphinx-favicon extention instead."
+        )
+
     # Validate icon links
     if not isinstance(theme_options.get("icon_links", []), list):
         raise ExtensionError(

tests/sites/deprecated/conf.py

@@ -27,6 +27,23 @@
         "sourcelink.html",
     ],
     "footer_items": ["page-toc.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

@@ -326,50 +326,6 @@ def test_logo_template_rejected(sphinx_build_factory):
         sphinx_build_factory("base", confoverrides=confoverrides).build()
 
 
-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()
@@ -884,6 +840,7 @@ def test_deprecated_build_html(sphinx_build_factory, file_regression):
     expected_warnings = (
         "The configuration `logo_text` is deprecated",
         "The configuration `page_sidebar_items` is deprecated",
+        "The configuration `favicons` is deprecated.",
         "`footer_items` is deprecated",
         "unsupported theme option 'logo_text'",
         "unsupported theme option 'page_sidebar_items'",