diff --git a/.github/workflows/lighthouserc.json b/.github/workflows/lighthouserc.json index 3931569031..4f00e9c3fc 100644 --- a/.github/workflows/lighthouserc.json +++ b/.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"] diff --git a/docs/_static/custom-icon.js b/docs/_static/custom-icons.js similarity index 73% rename from docs/_static/custom-icon.js rename to docs/_static/custom-icons.js index bc64dd6b9e..283602e15b 100644 --- a/docs/_static/custom-icon.js +++ b/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", + ], + }, ); diff --git a/docs/_static/pydata-icon.js b/docs/_static/pydata-icon.js deleted file mode 100644 index c43e98ebb0..0000000000 --- a/docs/_static/pydata-icon.js +++ /dev/null @@ -1,16 +0,0 @@ -/******************************************************************************* - * Set a custom icon for PyData - */ -FontAwesome.library.add( - (faListOldStyle = { - prefix: "fa-custom", - iconName: "pydata", - icon: [ - 24, // viewBox width - 24, // viewBox height - [], // ligature - "e002", // unicode codepoint - private use area - "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", - ], - }), -); diff --git a/docs/conf.py b/docs/conf.py index ee98e4c6db..b875808e74 100644 --- a/docs/conf.py +++ b/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 --------------------------------------------------------- diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index 5cd17577fd..bf41bbccd7 100644 --- a/docs/user_guide/header-links.rst +++ b/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 ```` tag and not ````! You can reference your custom FontAwesome icon in CSS using ``fa-``. +That's it, your icon will now be inserted with the ```` tag and not ````! You can reference your custom FontAwesome icon in CSS using the pattern ``.fa-`` , 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 diff --git a/webpack.config.js b/webpack.config.js index 70405300d4..05eaf25acd 100644 --- a/webpack.config.js +++ b/webpack.config.js @@ -74,7 +74,7 @@ function macroTemplate({ compilation }) { {% macro head_js_preload() %} - ${fa_scripts.map(script.bind(compilation)).join("\n")} + ${fa_scripts.map(deferScript.bind(compilation)).join("\n")} ${theme_scripts.map(preloadScript.bind(compilation)).join("\n")} {% endmacro %}