Replace in-tree sphinx extension with sphinx-favicon

This change has been previously proposed and agreed upon in #2869.

The idea here is to avoid the burden of maintaining an in-tree sphinx
extension, now that `sphinx-favicon` is available and covers setuptools
use-case.

2 files changed, 6 insertions, 65 deletions

diff --git a/docs/_ext/_custom_icons.py b/docs/_ext/_custom_icons.py
deleted file mode 100644
index 245162c2..00000000
--- a/docs/_ext/_custom_icons.py
+++ /dev/null
@@ -1,58 +0,0 @@
-"""'In-tree' sphinx extension to add icons/favicons to documentation"""
-import os
-from sphinx.util.fileutil import copy_asset_file
-
-
-IMAGES_DIR = "_images"  # same used by .. image:: and .. picture::
-
-
-def _prepare_image(pathto, confdir, outdir, icon_attrs):
-    """Copy icon files to the ``IMAGES_DIR`` and return a modified version of
-    the icon attributes dict replacing ``file`` with the correct ``href``.
-    """
-    icon = icon_attrs.copy()
-    src = os.path.join(confdir, icon.pop("file"))
-    if not os.path.exists(src):
-        raise FileNotFoundError(f"icon {src!r} not found")
-
-    dest = os.path.join(outdir, IMAGES_DIR)
-    copy_asset_file(src, dest)  # already compares if dest exists and is uptodate
-
-    asset_name = os.path.basename(src)
-    icon["href"] = pathto(f"{IMAGES_DIR}/{asset_name}", resource=True)
-    return icon
-
-
-def _link_tag(attrs):
-    return "<link " + " ".join(f'{k}="{v}"' for k, v in attrs.items()) + "/>"
-
-
-def _add_icons(app, _pagename, _templatename, context, doctree):
-    """Add multiple "favicons", not limited to PNG/ICO files"""
-    # https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs
-    # https://caniuse.com/link-icon-svg
-    try:
-        pathto = context['pathto']
-    except KeyError as ex:
-        msg = f"{__name__} extension is supposed to be call in HTML contexts"
-        raise ValueError(msg) from ex
-
-    if doctree and "icons" in app.config:
-        icons = [
-            _prepare_image(pathto, app.confdir, app.outdir, icon)
-            for icon in app.config["icons"]
-        ]
-        context["metatags"] += "\n".join(_link_tag(attrs) for attrs in icons)
-
-
-def setup(app):
-    images_dir = os.path.join(app.outdir, IMAGES_DIR)
-    os.makedirs(images_dir, exist_ok=True)
-
-    app.add_config_value("icons", None, "html")
-    app.connect("html-page-context", _add_icons)
-
-    return {
-        'parallel_read_safe': True,
-        'parallel_write_safe': True,
-    }
diff --git a/docs/conf.py b/docs/conf.py
index f6ccff0f..4a14214f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -179,23 +179,22 @@ towncrier_draft_include_empty = False
 extensions += ['jaraco.tidelift']
 
 # Add icons (aka "favicons") to documentation
-sys.path.append(os.path.join(os.path.dirname(__file__), '_ext'))
-extensions += ['_custom_icons']
+extensions += ['sphinx-favicon']
+html_static_path = ['images']  # should contain the folder with icons
 
 # List of dicts with <link> HTML attributes
-# as defined in https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link
-# except that ``file`` gets replaced with the correct ``href``
-icons = [
+# static-file points to files in the html_static_path (href is computed)
+favicons = [
     {  # "Catch-all" goes first, otherwise some browsers will overwrite
         "rel": "icon",
         "type": "image/svg+xml",
-        "file": "images/logo-symbol-only.svg",
+        "static-file": "logo-symbol-only.svg",
         "sizes": "any"
     },
     {  # Version with thicker strokes for better visibility at smaller sizes
         "rel": "icon",
         "type": "image/svg+xml",
-        "file": "images/favicon.svg",
+        "static-file": "favicon.svg",
         "sizes": "16x16 24x24 32x32 48x48"
     },
     # rel="apple-touch-icon" does not support SVG yet