DEV - Add Fontawesome scripts to build assets #1982

trallard · 2024-09-12T17:10:05Z

I seem to have forgotten to add the FA scripts to the pyproject.toml so I am adding it here (which should fix the FA rendering issue in the dev version of the docs).

@gabalafou Additionally, there seems to be a new issue: Uncaught ReferenceError: FontAwesome is not defined at... where we add the custom PyData and PyPI icons. However, I do not know how to resolve this (this is beyond my JS knowledge).

There is this document on customizing https://github.com/FortAwesome/Font-Awesome/wiki/Customize-Font-Awesome, which might be helpful for you. Could you please have a look?

github-actions · 2024-09-12T17:19:15Z

Coverage report

This PR does not seem to contain any modification to coverable code.

gabalafou · 2024-09-13T18:34:39Z

ENH - Update bundling and vendoring (JS) #1955

gabalafou · 2024-09-16T21:27:43Z

I can explain your Uncaught ReferenceError and offer a way to solve it.

We are dealing with a dependency failure between two scripts:

fontawesome.js
custom-icon.js

The Font Awesome library needs to be loaded first because the custom icon script calls it like so:

FontAwesome.library.add(/* icon object */)

The Font Awesome and custom icon scripts are loaded with different Jinja macros at different points in the layout template (which is the base template for all of the pages in the docs). Going from the top to the bottom of the template, here is a list of the relevant macros:

head_pre_icons() - prior to PR 1955, this macro loaded the Font Awesome script. It is located in the HTML <head>.
script() - Sphinx defines this macro. It also defines the Jinja {% block scripts %} and calls the macro within this block. Sphinx puts this block in the HTML <head> and we made sure to call the head_pre_icons() macro before this macro.
body_post() - after PR 1955 (and at the time of this writing), this macro loads the Font Awesome script. It is located near the end of the </body>.

So this is the problem. The custom icon script depends on the Font Awesome script. Before PR 1955, the Font Awesome script was loaded before the custom icon script. Now it's loaded after. So when the custom icon script executes, it references an undefined global, FontAwesome, and throws an uncaught error.

There are a number of different ways we could try to solve this, but the most straightforward is to restore the head_pre_icons() macro and load the Font Awesome script there like before. That's what I think we should do in the short-term even it undoes the performance gain of moving the Font Awesome script tag to the bottom of the page. We can then take some time to think more carefully about how to optimize the page load.

Note that PR 1955 also added the defer attribute to the Font Awesome script tag. We also have to undo that because defer has an effect that is similar to moving the script tag to the bottom of the page.

trallard · 2024-09-18T14:36:51Z

Thanks @gabalafou to fix the immediate issues with FA I added the FontAwesome JS scripts to the <head> and will look into further improvements later on

trallard · 2024-09-18T14:37:58Z

Will also mark this as a release blocker as we need to get this merged to ensure that FA is properly vendored for end-users

gabalafou

I'm not sure about that fontawesome.min.js import...

webpack.config.js

gabalafou · 2024-09-20T16:31:49Z

src/pydata_sphinx_theme/assets/scripts/fontawesome.js


+import "@fortawesome/fontawesome-free/js/fontawesome.min.js";


Why is this import needed?

Testing locally, if I remove fontawesome.min.js (but leave all.min.js) everything looks right on the home page. If I remove all.min.js (but leave fontawesom.min.js) the home page is missing icons.

Seems like only all.min.js needs to be imported here?

I followed the docs at https://docs.fontawesome.com/web/setup/host-yourself/svg-js (this is also what we had before).

I think because fontawesome.js is the loader, we need that to allow for custom icons to be added through FontAwesome.library.add() all.min.js should only be the SVG icons (need to check, unless it is a catch all for utilities + icons). But it seems to work without it because we are getting the core utilities and icons via the css/scss version of FA anyway.

This is why I am considering getting rid of the scss/css vendors so we can only deal with one at a time; otherwise, it is really confusing to debug and have a clean picture of the dependencies. I can remove it at is seems to work but I am not happy with having both the scss/css and JS versions of FA right now.e

Hmm. My knowledge of Font Awesome is shaky but I think the approach we're taking now is some kind of hybrid of the package manager and svg-js approaches.

There is a Font Awesome Python/Django docs page that says:

We have also provided a shortcut all.min.js or all.min.css file that includes all the Free icons as well as the core utility functions and styles. It’s a handy shortcut but isn’t as performant as selecting individual styles.

My understanding is that because we advertise PST as "Font Awesome Free included," we have to:

Include all three of the free icon sets (regular, solid, and brand)

Include both the svg+js and web fonts+css methods of using those icons, which means we have to ship both all.js and all.css down the wire to the end user.

Hmm. My knowledge of Font Awesome is shaky but I think the approach we're taking now is some kind of hybrid of the package manager and svg-js approaches.

This is correct. We are doing some things from one and some from the other. This means we are vendoring both the JS and CSS FA variants (which have performance and maintenance overheads).

Include both the svg+js and web fonts+css methods of using those icons, which means we have to ship both all.js and all.css down the wire to the end user.

That is incorrect. We only need one or the other from the Python docs you linked to:

We have also provided a shortcut all.min.js OR all.min.css file that includes all the Free icons as well as the core utility functions and styles.

The or is the crucial part; regardless of how we vendor FA, the CSS or JS approach provides the same functionalities and end-user experience (syntax and use of the icons are the same functionally).
We only need to chose one and stick to it (of course this would mean some refactor in the codebase) but ultimately users of PST should have the same experience of "FA included".

webpack.config.js

gabalafou · 2024-09-20T20:02:42Z

src/pydata_sphinx_theme/assets/scripts/fontawesome.js


+import "@fortawesome/fontawesome-free/js/fontawesome.min.js";


Hmm. My knowledge of Font Awesome is shaky but I think the approach we're taking now is some kind of hybrid of the package manager and svg-js approaches.

There is a Font Awesome Python/Django docs page that says:

We have also provided a shortcut all.min.js or all.min.css file that includes all the Free icons as well as the core utility functions and styles. It’s a handy shortcut but isn’t as performant as selecting individual styles.

My understanding is that because we advertise PST as "Font Awesome Free included," we have to:

Include all three of the free icon sets (regular, solid, and brand)

Include both the svg+js and web fonts+css methods of using those icons, which means we have to ship both all.js and all.css down the wire to the end user.

trallard · 2024-09-27T13:48:16Z

Since I pushed changes to the function names, I need another review by @gabalafou.
Can you please approve and merge? TY.

gabalafou

Code changes look fine.

It looks like all of the icons load on the three following preview URLs:

And I did not see any related errors in the browser console or network log. Thus, I approve. Thanks for getting this through @trallard!

I seem to have forgotten to add the FA scripts to the `pyproject.toml` so I am adding it here (which should fix the FA rendering issue in the dev version of the docs). --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

trallard added 2 commits September 5, 2024 18:56

🔧 Update static assets list

f962ec3

Remove straggling debug string

1342a23

trallard added tag: dependencies Pull requests that update a dependency file tag: javascript Pull requests that update Javascript code labels Sep 12, 2024

trallard marked this pull request as draft September 12, 2024 17:10

trallard added 2 commits September 18, 2024 15:34

Add FA.JS to head

68b2649

Merge branch 'main' into trallard/patch-JS-bundle

c3f822b

trallard marked this pull request as ready for review September 18, 2024 14:35

[pre-commit.ci] Automatic linting and formatting fixes

97fefab

trallard requested a review from gabalafou September 18, 2024 14:36

trallard added the impact: block-release Should block a release from happening. Only use if this is a critical problem we don't want to ship label Sep 18, 2024

gabalafou mentioned this pull request Sep 19, 2024

Team sync - Sep 19th, 2024 Quansight-Labs/czi-scientific-python-mgmt#126

Open

trallard changed the title ~~WIP - Add Fontawesome scripts to build assets~~ DEV - Add Fontawesome scripts to build assets Sep 19, 2024

gabalafou requested changes Sep 20, 2024

View reviewed changes

Remove FA import

7e8786a

gabalafou previously approved these changes Sep 20, 2024

View reviewed changes

Rename functions

d7dc53f

trallard dismissed gabalafou’s stale review via d7dc53f September 27, 2024 13:46

trallard requested a review from gabalafou September 27, 2024 13:48

drammock mentioned this pull request Sep 27, 2024

Release 0.16.0 #1948

Open

10 tasks

gabalafou approved these changes Sep 27, 2024

View reviewed changes

gabalafou merged commit e7e9749 into pydata:main Sep 27, 2024
25 checks passed

trallard deleted the trallard/patch-JS-bundle branch September 27, 2024 16:00

gabalafou mentioned this pull request Oct 1, 2024

Team sync - September 26, 2024 Quansight-Labs/czi-scientific-python-mgmt#127

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DEV - Add Fontawesome scripts to build assets #1982

DEV - Add Fontawesome scripts to build assets #1982

trallard commented Sep 12, 2024

github-actions bot commented Sep 12, 2024

gabalafou commented Sep 13, 2024

gabalafou commented Sep 16, 2024

trallard commented Sep 18, 2024

trallard commented Sep 18, 2024

gabalafou left a comment

gabalafou Sep 20, 2024

trallard Sep 20, 2024 •

edited

Loading

gabalafou Sep 20, 2024

trallard Sep 23, 2024 •

edited

Loading

gabalafou Sep 20, 2024

trallard commented Sep 27, 2024

gabalafou left a comment


		import "@fortawesome/fontawesome-free/js/fontawesome.min.js";

DEV - Add Fontawesome scripts to build assets #1982

DEV - Add Fontawesome scripts to build assets #1982

Conversation

trallard commented Sep 12, 2024

github-actions bot commented Sep 12, 2024

Coverage report

gabalafou commented Sep 13, 2024

gabalafou commented Sep 16, 2024

trallard commented Sep 18, 2024

trallard commented Sep 18, 2024

gabalafou left a comment

Choose a reason for hiding this comment

gabalafou Sep 20, 2024

Choose a reason for hiding this comment

trallard Sep 20, 2024 • edited Loading

Choose a reason for hiding this comment

gabalafou Sep 20, 2024

Choose a reason for hiding this comment

trallard Sep 23, 2024 • edited Loading

Choose a reason for hiding this comment

gabalafou Sep 20, 2024

Choose a reason for hiding this comment

trallard commented Sep 27, 2024

gabalafou left a comment

Choose a reason for hiding this comment

trallard Sep 20, 2024 •

edited

Loading

trallard Sep 23, 2024 •

edited

Loading