Add option to disable TryExamples without rebuilding docs

[steppi]

This PR makes it so if a file entitled .disable_try_examples is added to the root level of the deployed documentation's build directory, "try examples" buttons will be hidden at page load time, effectively disabling interactive examples without requiring a documentation rebuild.

A Javascript function checks at page load for the presence of the file, and if so, hides the buttons.

In https://github.com/scipy/scipy/issues/19729#issuecomment-1875437428, @rgommers noted that it would be good to be able to disable the interactive examples without requiring a rebuild of the documentation. This is particularly helpful for SciPy with its long documentation build and deployment times.

[Carreau]

To make thinks a bit more automatic, I would take a peak at the URL and look at wether it contains /latest|/stable or similar, or at least something the file you look at could be a json with a list of url pattern where this should be enabled/disabled.

At least the latest/stable would allow to have automatic enabling/disabling automatically when new version is pushed on RTD

[steppi]

To make thinks a bit more automatic, I would take a peak at the URL and look at wether it contains /latest|/stable or similar, or at least something the file you look at could be a json with a list of url pattern where this should be enabled/disabled.

At least the latest/stable would allow to have automatic enabling/disabling automatically when new version is pushed on RTD

Having it be a json with a list of url patterns sounds like a good solution.

[steppi]

Thanks @Carreau! I've updated it to check for a json file .try_examples_ignore.json containing a list of regex patterns for files where interactive documentation should be disabled. I've been testing this locally, but can work on getting it set up for my experimental deployment at https://steppi.github.io/scipy/. A hiccup there is that I accidentally left circle ci enabled in my SciPy fork after building and deploying the docs the last time and ran out of credits for the month, so it's not as simple as just pushing a new commit where jupyterlite-sphinx is pinned to this PR branch.

Another thought I had is that it would be useful to be able to specify a default .try_examples_ignore.json in Sphinx's conf.py.

[steppi]

I've deployed the docs at https://steppi.github.io/scipy with jupyterlite-sphinx pinned to this PR branch and added an ignore file https://github.com/steppi/scipy/blob/gh-pages/.try_examples_ignore.json, which disables all linalg examples.

An example of a linalg example which is disabled: https://steppi.github.io/scipy/reference/generated/scipy.linalg.solve.html#scipy.linalg.solve

An example of a non-linalg example which is still live: https://steppi.github.io/scipy/reference/generated/scipy.cluster.hierarchy.linkage.html#scipy.cluster.hierarchy.linkage.

[steppi]

I've changed .try_examples_ignore.json to just a generic config file .try_examples.json and documented it as such, since we might want to add more runtime changeable options in the future. I've also made it possible to specify a default version of this file in the sphinx conf.py.

[Carreau]

From a discussion, maybe we should have a "force-enable" function in the browser javascript console to force-enable.

[steppi]

@Carreau, I've updated this to match url pathnames instead of sphinx docnames; use async/await instead of promises, and have added a function to toggle the visibility of the buttons for use from the console.

[Carreau]

Thanks, I think we should just merge and iterate, to see how it goes.

[martinRenou]

Thank you both!

[steppi]

Thanks @Carreau! I'll work on implementing your other suggestions today.