MAINT - Defer FontAwesome script to improve Lighthouse performance score

.github/workflows/lighthouserc.json

@@ -2,10 +2,16 @@
   "ci": {
     "collect": {
       "staticDistDir": "./audit/_build/",
-      "autodiscoverUrlBlocklist": [
-        "/genindex.html",
-        "/search.html",
-        "/_static/webpack-macros.html"
+      "url": [
+        "/admonitions.html",
+        "/api.html",
+        "/blocks.html",
+        "/generic.html",
+        "/lists.html",
+        "/really-long.html",
+        "/structure.html",
+        "/tables.html",
+        "/typography.html"
       ],
       "settings": {
         "skipAudits": ["canonical"]

docs/_static/custom-icon.js → docs/_static/custom-icons.js

@@ -1,16 +1,30 @@
-/*******************************************************************************
- * Set a custom icon for pypi as it's not available in the fa built-in brands
- */
 FontAwesome.library.add(
-  (faListOldStyle = {
+  /**
+   * Custom icon definitions
+   *
+   * see https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/header-links.html#svg-image-icons
+   */
+  {
     prefix: "fa-custom",
     iconName: "pypi",
     icon: [
-      17.313, // viewBox width
-      19.807, // viewBox height
-      [], // ligature
-      "e001", // unicode codepoint - private use area
-      "m10.383 0.2-3.239 1.1769 3.1883 1.1614 3.239-1.1798zm-3.4152 1.2411-3.2362 1.1769 3.1855 1.1614 3.2369-1.1769zm6.7177 0.00281-3.2947 1.2009v3.8254l3.2947-1.1988zm-3.4145 1.2439-3.2926 1.1981v3.8254l0.17548-0.064132 3.1171-1.1347zm-6.6564 0.018325v3.8247l3.244 1.1805v-3.8254zm10.191 0.20931v2.3137l3.1777-1.1558zm3.2947 1.2425-3.2947 1.1988v3.8254l3.2947-1.1988zm-8.7058 0.45739c0.00929-1.931e-4 0.018327-2.977e-4 0.027485 0 0.25633 0.00851 0.4263 0.20713 0.42638 0.49826 1.953e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36226 0.13215-0.65608-0.073306-0.65613-0.4588-6.28e-5 -0.38556 0.2938-0.80504 0.65613-0.93662 0.068422-0.024919 0.13655-0.038114 0.20156-0.039466zm5.2913 0.78369-3.2947 1.1988v3.8247l3.2947-1.1981zm-10.132 1.239-3.2362 1.1769 3.1883 1.1614 3.2362-1.1769zm6.7177 0.00213-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2439-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.016195v3.8275l3.244 1.1805v-3.8254zm16.9 0.21143-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2432-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.019027v3.8247l3.244 1.1805v-3.8254zm13.485 1.4497-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm2.4018 0.38127c0.0093-1.83e-4 0.01833-3.16e-4 0.02749 0 0.25633 0.0085 0.4263 0.20713 0.42638 0.49826 1.97e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36188 0.1316-0.65525-0.07375-0.65542-0.4588-1.95e-4 -0.38532 0.29328-0.80469 0.65542-0.93662 0.06842-0.02494 0.13655-0.03819 0.20156-0.03947zm-5.8142 0.86403-3.244 1.1805v1.4201l3.244 1.1805z", // svg path (https://simpleicons.org/icons/pypi.svg)
+      17.313,
+      19.807,
+      [],
+      "e001",
+      // https://simpleicons.org/icons/pypi.svg
+      "m10.383 0.2-3.239 1.1769 3.1883 1.1614 3.239-1.1798zm-3.4152 1.2411-3.2362 1.1769 3.1855 1.1614 3.2369-1.1769zm6.7177 0.00281-3.2947 1.2009v3.8254l3.2947-1.1988zm-3.4145 1.2439-3.2926 1.1981v3.8254l0.17548-0.064132 3.1171-1.1347zm-6.6564 0.018325v3.8247l3.244 1.1805v-3.8254zm10.191 0.20931v2.3137l3.1777-1.1558zm3.2947 1.2425-3.2947 1.1988v3.8254l3.2947-1.1988zm-8.7058 0.45739c0.00929-1.931e-4 0.018327-2.977e-4 0.027485 0 0.25633 0.00851 0.4263 0.20713 0.42638 0.49826 1.953e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36226 0.13215-0.65608-0.073306-0.65613-0.4588-6.28e-5 -0.38556 0.2938-0.80504 0.65613-0.93662 0.068422-0.024919 0.13655-0.038114 0.20156-0.039466zm5.2913 0.78369-3.2947 1.1988v3.8247l3.2947-1.1981zm-10.132 1.239-3.2362 1.1769 3.1883 1.1614 3.2362-1.1769zm6.7177 0.00213-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2439-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.016195v3.8275l3.244 1.1805v-3.8254zm16.9 0.21143-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2432-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.019027v3.8247l3.244 1.1805v-3.8254zm13.485 1.4497-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm2.4018 0.38127c0.0093-1.83e-4 0.01833-3.16e-4 0.02749 0 0.25633 0.0085 0.4263 0.20713 0.42638 0.49826 1.97e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36188 0.1316-0.65525-0.07375-0.65542-0.4588-1.95e-4 -0.38532 0.29328-0.80469 0.65542-0.93662 0.06842-0.02494 0.13655-0.03819 0.20156-0.03947zm-5.8142 0.86403-3.244 1.1805v1.4201l3.244 1.1805z",
     ],
-  }),
+  },
+  {
+    prefix: "fa-custom",
+    iconName: "pydata",
+    icon: [
+      24,
+      24,
+      [],
+      "e002",
+      "M12.1,17.8v5.8l-5-2.9v-5.8L12.1,17.8z M12.1,12v5.8l-5-2.9V9.1L12.1,12z M17,9.1L12.1,12v5.8l4.9-2.9V9.1z M12.1,6.2L7,9.1l5,2.9L17,9.1L12.1,6.2z M17,9.1V3.3l-4.9-2.8v5.8L17,9.1z",
+    ],
+  },
 );

docs/conf.py

@@ -257,7 +257,9 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
-html_js_files = ["pydata-icon.js", "custom-icon.js"]
+html_js_files = [
+    ("custom-icons.js", {"defer": "defer"}),
+]
 todo_include_todos = True
 
 # -- favicon options ---------------------------------------------------------

docs/user_guide/header-links.rst

@@ -205,38 +205,54 @@ SVG image icons
 In order to make use of the full feature set of ``.svg`` images provided by HTML you will need
 to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly straightforward process:
 
-#. Copy the contents of ``custom-icon.js`` - located within the ``docs`` tree - into an appropriate directory of your documentation
-   source (typically ``source/js``) and rename the file however you like. Highlighted below are the lines which must be modified
+#. Copy `custom-icons.js`_ into an appropriate directory of your documentation
+   source (typically ``source/js``). In that file you will find a list of custom
+   icon definitions. Each definition looks like this:
 
    .. code:: javascript
 
-     prefix: "fa-custom",
-     iconName: "pypi",
-     icon: [
-       17.313, // viewBox width
-       19.807, // viewBox height
-       [], // ligature
-       "e001", // unicode codepoint - private use area
-       "m10.383 0.2-3.239 ...", // string definined SVG path
-     ],
-
+     {
+       prefix: "fa-custom",
+       iconName: "pypi",
+       icon: [
+         17.313, // viewBox width
+         19.807, // viewBox height
+         [], // ligature
+         "e001", // unicode codepoint - private use area
+         "m10.383 0.2-3.239 ...", // svg path
+       ],
+     }
 
-#. Update the following file contents:
+#. Remove the existing list of icon definitions and add your own using the same pattern as above:
 
-   #.  ``iconName``  to be one of our choosing
-   #.  Change the viewbox height and width to match that of your icon
-   #.  Replace the SVG path string with the path which defines your custom icon
+   #.  Keep the value of ``prefix`` as "fa-custom"
+   #.  Set the value of ``iconName``  to a short, sensible, lowercase name for your icon
+   #.  Change the view box height and width to match that of your icon
+   #.  For each custom icon you define in the list, increment the Unicode codepoint by 1: ``"e001"``, ``"e002"``, ``"e003"``...
+   #.  Replace the SVG path string with the path that defines your custom icon
 
-#. Add the relative path from your source directory to the custom javascript file to your ``conf.py``:
+#. In ``conf.py``, add the relative path from your source directory to the custom javascript file:
 
    .. code:: python
 
       html_js_files = [
          ...
-         "js/pypi-icon.js",
+         ("js/custom-icons.js", {"defer": "defer"}),
          ...
       ]
 
+   .. versionchanged:: v0.17.0
+
+      ``defer`` attribute is required.
+
+   .. important::
+
+      Do not add more than one ``custom-icons.js`` file in your ``conf.py``.
+
+      Each custom icon js file includes a call to ``FontAwesome.library.add()``.
+      Your site's JavaScript can only call that function once. In our testing,
+      subsequent calls to that function do not load additional icons.
+
 #. Set up the icon link in the ``html_theme_options`` as a FontAwesome icon:
 
    .. code:: python
@@ -254,7 +270,7 @@ to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly s
          ...
       ]
 
-That's it, your icon will now be inserted with the ``<svg>`` tag and not ``<img>``! You can reference your custom FontAwesome icon in CSS using ``fa-<custom-name>``.
+That's it, your icon will now be inserted with the ``<svg>`` tag and not ``<img>``! You can reference your custom FontAwesome icon in CSS using the pattern ``.fa-<iconName>`` , for example ``.fa-pypi``.
 
 .. _icon-link-shortcuts:
 
@@ -309,3 +325,5 @@ For example, to specify a custom ``target`` and ``rel`` attribute, and to define
 
 .. warning::
    This might make your icon links behave unexpectedly and might override the default behavior, so make sure you know what you're doing!
+
+.. _custom-icons.js: ../_static/custom-icons.js

webpack.config.js

@@ -74,7 +74,7 @@ function macroTemplate({ compilation }) {
 
     {% macro head_js_preload() %}
       <!-- So that users can add custom icons -->
-      ${fa_scripts.map(script.bind(compilation)).join("\n")}
+      ${fa_scripts.map(deferScript.bind(compilation)).join("\n")}
       <!-- Pre-loaded scripts that we'll load fully later -->
       ${theme_scripts.map(preloadScript.bind(compilation)).join("\n")}
     {% endmacro %}