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

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

Author: 12rambau

docs/_static/android-chrome-192x192.png

@@ -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/_static/android-chrome-512x512.png

@@ -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.