Add option to disable TryExamples without rebuilding docs #118

steppi · 2024-01-10T01:22:24Z

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 scipy/scipy#19729 (comment), @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 · 2024-01-10T12:22:24Z

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

Carreau · 2024-01-10T13:17:25Z

jupyterlite_sphinx/jupyterlite_sphinx.js

+            }
+	}
+    });
+}


Also you have a mix of tabs and spaces :-)

https://www.youtube.com/watch?v=SsoOG6ZeyUI

Ha. I use Emacs and for languages I use regularly, I have it set up to handle the indentation automatically. I guess the out of the box Javascript mode isn’t doing that properly. I’ll look into installing proper tooling.

steppi · 2024-01-10T14:41:52Z

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 · 2024-01-10T19:22:41Z

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 · 2024-01-11T01:25:50Z

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.

- might want to add more options later

- sorry, really need to look into configuring emacs properly

steppi · 2024-01-11T15:57:18Z

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 · 2024-01-15T14:41:49Z

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

Carreau

Miscelaneous comments.

docs/directives/try_examples.md

Carreau · 2024-01-16T09:50:51Z

docs/directives/try_examples.md

+`TryExamples` buttons will be hidden in files matching at least one of these patterns,
+effectively disabling the interactive documentation. In the provided example:


Do we want those to match files, or final URLs ?

Carreau · 2024-01-16T09:54:50Z

jupyterlite_sphinx/jupyterlite_sphinx.js

+        .then(response => {
+            if (!response.ok) {
+                if (response.status === 404) {
+                    // try examples ignore file is not present.
+                    return null;
+                }
+                throw new Error(`Error fetching ${ignoreFilePath}`);
+            }
+            return response.json();
+        })
+        .then(data => {
+            if (!data) {
+                return;
+            }
+            // Disable interactive examples if file matches one of the ignore patterns
+            // by hiding try_examples_buttons.
+            const regexPatterns = data.ignore_patterns;
+            for (let pattern of regexPatterns) {
+                let regex = new RegExp(pattern);
+                if (regex.test(currentPagePath)) {
+                    var buttons = document.getElementsByClassName('try_examples_button');
+                    for (var i = 0; i < buttons.length; i++) {
+                        buttons[i].classList.add('hidden');
+                    }
+                    break;
+                }
+            }
+        })
+        .catch(error => {
+            console.error(error);
+        });


I talk to some local colleagues, and they told that most recent browser support top level await, so I think we canlater refactor into clearer code and avoid promises.

Carreau · 2024-01-16T09:56:48Z

jupyterlite_sphinx/jupyterlite_sphinx.py

+            "<script>"
+            'document.addEventListener("DOMContentLoaded", function() {'
+            f'window.loadTryExamplesConfig("{config_path}","{docname}");'
+            "});"
+            "</script>"


I think we want the regex to match urls, that way if say on readthedocs we can have only /stable/ and /latest/ to show JupyterLight buttons, but not older version.

Ah, true. Mix up on my part. I didn't consider that we'd have two sets of deployed docs with different doc roots one at base_url + '/stable' and the other at base_url + '/latest'. I was thinking of the case where / is the doc root, and it has subfolders /stable and /latest, which isn't how things would typically work.

Co-authored-by: M Bussonnier <[email protected]>

steppi · 2024-01-16T20:07:38Z

@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 · 2024-01-24T09:30:17Z

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

martinRenou · 2024-01-24T09:35:50Z

Thank you both!

steppi · 2024-01-24T13:55:24Z

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

steppi added 2 commits January 9, 2024 19:42

Add option to disable try_examples without rebuild

70ea1f0

Add note .disable_try_examples file

3ee2b99

martinRenou added the enhancement New feature or request label Jan 10, 2024

Carreau reviewed Jan 10, 2024

View reviewed changes

steppi added 4 commits January 10, 2024 12:27

Remove tabs from indentation in js file

78f9284

Add more flexibility to try examples ignore behavior

d7e4322

Update documentation for disabling without rebuilding

2cbea45

Black format code

cdcbec8

Add back cache busting

f4b77fc

steppi force-pushed the disable branch from e6dc4bd to f4b77fc Compare January 11, 2024 00:23

steppi added 4 commits January 11, 2024 09:51

Change .try_examples_ignore.json to general config .try_examples.json

813c272

- might want to add more options later

Add default runtime config

69af3fe

Document default config option

b594599

Remove tabs from js file

e9cb91b

- sorry, really need to look into configuring emacs properly

Carreau approved these changes Jan 16, 2024

View reviewed changes

steppi and others added 5 commits January 16, 2024 08:47

Update docs/directives/try_examples.md

d3679b0

Co-authored-by: M Bussonnier <[email protected]>

Match url instead of doc file path in ignore patterns

a678a24

Update docs for match urls instead of filepaths

8eccefe

Change to use async await instead of promises

0fec48d

Add function to toggle TryExamples buttons from console

b2fc6db

Carreau merged commit 308034d into jupyterlite:main Jan 24, 2024

		`TryExamples` buttons will be hidden in files matching at least one of these patterns,
		effectively disabling the interactive documentation. In the provided example:

Add option to disable TryExamples without rebuilding docs #118

Add option to disable TryExamples without rebuilding docs #118

Uh oh!

Conversation

steppi commented Jan 10, 2024

Uh oh!

Carreau commented Jan 10, 2024

Uh oh!

Carreau Jan 10, 2024

Choose a reason for hiding this comment

Uh oh!

martinRenou Jan 10, 2024

Choose a reason for hiding this comment

Uh oh!

steppi Jan 10, 2024

Choose a reason for hiding this comment

Uh oh!

steppi commented Jan 10, 2024

Uh oh!

steppi commented Jan 10, 2024

Uh oh!

steppi commented Jan 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steppi commented Jan 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Carreau commented Jan 15, 2024

Uh oh!

Carreau left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Carreau Jan 16, 2024

Choose a reason for hiding this comment

Uh oh!

Carreau Jan 16, 2024

Choose a reason for hiding this comment

Uh oh!

Carreau Jan 16, 2024

Choose a reason for hiding this comment

Uh oh!

steppi Jan 16, 2024

Choose a reason for hiding this comment

Uh oh!

steppi commented Jan 16, 2024

Uh oh!

Carreau commented Jan 24, 2024

Uh oh!

martinRenou commented Jan 24, 2024

Uh oh!

steppi commented Jan 24, 2024

Uh oh!

Uh oh!

steppi commented Jan 11, 2024 •

edited

Loading

steppi commented Jan 11, 2024 •

edited

Loading