Add favicons option for defining multiple favicons (#359)

Author: tcmetzger

docs/user_guide/configuring.rst

@@ -121,6 +121,49 @@ an external site. You can add external links to the nav bar like so:
      ]
    }
 
+Adding 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``.
+
+Additionally, ``pydata_sphinx_theme`` allows you to add any number of
+browser- or device-specific favicons of any size. To define arbitrary favicons,
+use the ``favicons`` configuration key. The ``href`` value can be either an
+absolute URL (beginning with ``http``) or a local path relative to your
+``html_static_path``:
+
+.. code-block:: python
+
+   html_theme_options = {
+      "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"
+         },
+      ]
+   }
+
+``pydata_sphinx_theme`` will add ``link`` tags to your document's ``head``
+section, following this pattern:
+
+.. code-block:: html+jinja
+
+   <link rel="{{ favicon.rel }}" sizes="{{ favicon.sizes }}" href="{{ favicon.href }}">
+
+
 .. _configure-sidebar:
 
 Configure the sidebar

pydata_sphinx_theme/layout.html

@@ -24,6 +24,13 @@
 {%- block extrahead %}
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="docsearch:language" content="en" />
+    {% for favicon in theme_favicons %}
+      {% if favicon.href[:4] == 'http'%}
+      <link rel="{{ favicon.rel }}" sizes="{{ favicon.sizes }}" href="{{ favicon.href }}">
+      {% else %}
+      <link rel="{{ favicon.rel }}" sizes="{{ favicon.sizes }}" href="{{ pathto('_static/' + favicon.href, 1) }}">
+      {% endif %}
+    {% endfor %}
 {%- endblock %}
 
 {# Silence the sidebar's, relbar's #}

pydata_sphinx_theme/theme.conf

@@ -15,6 +15,7 @@ twitter_url =
 icon_links_label = Icon Links
 icon_links =
 google_analytics_id =
+favicons =
 show_prev_next = True
 search_bar_text = Search the docs ...
 search_bar_position = sidebar

tests/test_build.py

@@ -113,6 +113,47 @@ def test_logo_name(sphinx_build_factory):
     assert "PyData Tests" in index_html.select(".navbar-brand")[0].text.strip()
 
 
+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"/>'
+    )
+    icon_32 = '<link href="_static/favicon-32x32.png" rel="icon" sizes="32x32"/>'
+    icon_180 = (
+        '<link href="_static/apple-touch-icon-180x180.png" '
+        'rel="apple-touch-icon" sizes="180x180"/>'
+    )
+
+    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_sidebar_default(sphinx_build_factory):
     """The sidebar is shrunk when no sidebars specified in html_sidebars."""
     sphinx_build = sphinx_build_factory("base").build()