Hide buttons generated by the TryExamples directive by default

[agriyakhetarpal]

Description

This PR hides the buttons from the TryExamples directive by default. This is helpful because the current method of ignoring particular pages based on their URL first loads the buttons and then hides them, which means that they are briefly displayed on that page in the documentation and then hidden – keeping them hidden and then selectively enabling them will minimise this latency and improve user experience.

Changes made

1. Made all try_examples_button buttons hidden at the time of generation by adding this keyword to the classList
2. Updated the loadTryExamplesConfig function in jupyterlite_sphinx.js to check for the try_examples_button hidden class instead and then remove hidden from the classList

Additional context

N/A

[agriyakhetarpal]

I have rebased this right now and opened a PR because I think it will be better for visibility, plus I would appreciate some help towards bringing this to completion. It's not fully working right now since the directives still seem to contain the try_examples_button hidden and therefore are not displayed, even when I try to remove the keyword from the classList. It has been a while since I worked on this, so I'm not sure what I was debugging back then.

[Carreau]

I see why this is reasonable, but isn't that going to have the opposite effect on page where the button should be visible, where the page will load and then jump around as buttons are added ?

[agriyakhetarpal]

I see why this is reasonable, but isn't that going to have the opposite effect on page where the button should be visible, where the page will load and then jump around as buttons are added ?

Thanks for the review, @Carreau. Yes, this will be a slight issue when someone reloads a page and if they are in the middle of a page when doing so – but at the top of the page, it should load as normal, because from there the buttons will be appended to the layout rather than being inserted into a position where the text moves because of the insertion. I am not sure if there is a cleaner way to do this.

[agriyakhetarpal]

I think this is partially working now – where it breaks is when a try_examples.json config file is not present, and therefore data.ignore_patterns will always be false. I'll try to move the logic for un-hiding the buttons into a separate function and then call it. This way, the currently hidden buttons can be un-hidden with or without the presence of the configuration file.

[agriyakhetarpal]

I think this is working now, marking it as ready for review. One small thing to figure out remains: the PR preview at https://jupyterlite-sphinx--173.org.readthedocs.build/en/173/directives/try_examples.html is not un-hiding the button with the custom blue-bottom CSS present in jupyterlite_sphinx.css. The button is visible in the stable documentation: https://jupyterlite-sphinx.readthedocs.io/en/stable/directives/try_examples.html

So this works for all sorts of buttons now (tested locally), except for these non-standard buttons that have user-defined CSS. Let me try to dig further, and meanwhile open this up for further comments.

[Carreau]

I will try to re-review.

I'm ok with this in principle. Still unsure if hiding or appending is the best, so I'd like someone else input on this anyway.

[agriyakhetarpal]

I think this is working now, marking it as ready for review. One small thing to figure out remains: the PR preview at jupyterlite-sphinx--173.org.readthedocs.build/en/173/directives/try_examples.html is not un-hiding the button with the custom blue-bottom CSS present in jupyterlite_sphinx.css. The button is visible in the stable documentation: jupyterlite-sphinx.readthedocs.io/en/stable/directives/try_examples.html

So this works for all sorts of buttons now (tested locally), except for these non-standard buttons that have user-defined CSS. Let me try to dig further, and meanwhile open this up for further comments.

Update on this: With the refactoring I performed in my recent commits, I've fixed the problem I had noted above; however, using it on projects downstream, such as NumPy, fails, and I am not able to un-hide the buttons selectively based on the config file. So far, I still haven't been able to figure out why (it apparently has something to do with the CSS rather than with JS).

Even though this is marked as a draft, it's ready for review – @Carreau, could you please re-review it when you have time? I discussed this PR with @steppi, who agreed to review it soon after I suggested that I would revisit it, which I now have. Perhaps some trained pairs of eyes will be able to catch issues I haven't been able to :D

Also, a note on the jumping around of the contents when the page is loaded: I've tried to implement a solution (not pushed here, though, it should probably be a separate PR) to minimise the CLS value, through pre-allocating space for the container where the button is going to show up. However, for pages where the buttons are ignored/hidden, this check happens at runtime through the JavaScript code – which is not ideal. To achieve a smooth experience and no shifts in the content in the truest sense, this is possible only if we read through the documentation source pages and exclude them based on ignore patterns at build time (i.e., which would be read within the TryExamplesDirective class on the Python side), rather than at runtime on the JavaScript side, so that we avoid adding the HTML for the buttons altogether in the first place for pages where we need to ignore adding examples. I managed to get started on it, but I'm yet to test it (and I feel that should be in a separate PR, too).