Merge pull request #118 from steppi/disable

Add option to disable TryExamples without rebuilding docs

Author: Carreau

docs/directives/try_examples.md

@@ -166,3 +166,41 @@ allowing for specification of examples sections which should not be made interac
 If you are using the `TryExamples` directive in your documentation, you'll need to ensure
 that the version of the package installed in the Jupyterlite kernel you are using
 matches that of the version you are documenting.
+
+## Configuration without rebuilding
+
+The `TryExamples` directive supports disabling interactive examples without rebuilding
+the documentation. This can be helpful for projects requiring substantial documentation
+build time. Users may add a json config file entitled `.try_examples.json` to the root
+directory of the build directory for the deployed documentation. The format is a list of
+[JavaScript Regex patterns](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) attached to the key `"ignore_patterns"` like below.
+
+```json
+{
+    "ignore_patterns": ["^/latest/.*", "^/stable/reference/generated/example.html"]
+}
+```
+
+`TryExamples` buttons will be hidden in url pathnames matching at least one of these
+patterns, effectively disabling the interactive documentation. In the provided example:
+
+* The pattern `".*latest/.*" disables interactive examples for urls for the documentation
+  for the latest version of the package, which may be useful if this documentation is
+  for a development version for which a corresponding package build is not available
+  in a Jupyterlite kernel.
+
+* The pattern `".*stable/reference/generated/example.html"` targets a particular url
+  in the documentation for the latest stable release. 
+
+Note that these patterns should match the [pathname](https://developer.mozilla.org/en-US/docs/Web/API/Location/pathname) of the url, not the full url. This is the path portion of
+the url. For instance, the pathname of https://jupyterlite-sphinx.readthedocs.io/en/latest/directives/try_examples.html is `/en/latest/directives/try_examples.html`.
+
+
+A default configuration file can be specified in `conf.py` with the option
+`try_examples_default_runtime_config`.
+
+```python
+try_examples_default_runtime_config = {
+    "ignore_patterns": ["^/latest/.*", "^/stable/reference/generated/example.html"]
+}
+```

jupyterlite_sphinx/jupyterlite_sphinx.js

@@ -52,18 +52,18 @@ window.tryExamplesShowIframe = (
     let iframe = iframeContainer.querySelector('iframe.jupyterlite_sphinx_raw_iframe');
 
     if (!iframe) {
-	      const examples = examplesContainer.querySelector('.try_examples_content');
-	      iframe = document.createElement('iframe');
-	      iframe.src = iframeSrc;
-	      iframe.style.width = '100%';
+              const examples = examplesContainer.querySelector('.try_examples_content');
+              iframe = document.createElement('iframe');
+              iframe.src = iframeSrc;
+              iframe.style.width = '100%';
               minHeight = parseInt(iframeMinHeight);
-	      height = Math.max(minHeight, examples.offsetHeight);
-	      iframe.style.height = `${height}px`;
-	      iframe.classList.add('jupyterlite_sphinx_raw_iframe');
-	      examplesContainer.classList.add("hidden");
-	      iframeContainer.appendChild(iframe);
+              height = Math.max(minHeight, examples.offsetHeight);
+              iframe.style.height = `${height}px`;
+              iframe.classList.add('jupyterlite_sphinx_raw_iframe');
+              examplesContainer.classList.add("hidden");
+              iframeContainer.appendChild(iframe);
     } else {
-	      examplesContainer.classList.add("hidden");
+              examplesContainer.classList.add("hidden");
     }
     iframeParentContainer.classList.remove("hidden");
 }
@@ -76,3 +76,57 @@ window.tryExamplesHideIframe = (examplesContainerId, iframeParentContainerId) =>
     iframeParentContainer.classList.add("hidden");
     examplesContainer.classList.remove("hidden");
 }
+
+
+window.loadTryExamplesConfig = async (ignoreFilePath) => {
+    try {
+        // Add a timestamp as query parameter to ensure a cached version of the
+        // file is not used.
+        const timestamp = new Date().getTime();
+        const ignoreFileUrl = `${ignoreFilePath}?cb=${timestamp}`;
+        const currentPageUrl = window.location.pathname;
+
+        const response = await fetch(ignoreFileUrl);
+        if (!response.ok) {
+            if (response.status === 404) {
+                // Try examples ignore file is not present.
+                console.log('Ignore file not found.');
+                return;
+            }
+            throw new Error(`Error fetching ${ignoreFilePath}`);
+        }
+
+        const data = await response.json();
+        if (!data) {
+            return;
+        }
+
+        // Disable interactive examples if file matches one of the ignore patterns
+        // by hiding try_examples_buttons.
+        Patterns = data.ignore_patterns;
+        for (let pattern of Patterns) {
+            let regex = new RegExp(pattern);
+            if (regex.test(currentPageUrl)) {
+                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);
+    }
+};
+
+
+window.toggleTryExamplesButtons = () => {
+    /* Toggle visibility of TryExamples buttons. For use in console for debug
+     * purposes. */
+    var buttons = document.getElementsByClassName('try_examples_button');
+
+    for (var i = 0; i < buttons.length; i++) {
+        buttons[i].classList.toggle('hidden');
+    }
+
+};

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -530,7 +530,18 @@ def run(self):
             "", f"<style>{complete_button_css}</style>", format="html"
         )
 
-        return [content_container_node, notebook_container, style_tag]
+        # Search cnofig file allowing for config changes without rebuilding docs.
+        config_path = os.path.join(relative_path_to_root, ".try_examples.json")
+        script_html = (
+            "<script>"
+            'document.addEventListener("DOMContentLoaded", function() {'
+            f'window.loadTryExamplesConfig("{config_path}");'
+            "});"
+            "</script>"
+        )
+        script_node = nodes.raw("", script_html, format="html")
+
+        return [content_container_node, notebook_container, style_tag, script_node]
 
 
 def _process_docstring_examples(app, docname, source):
@@ -563,6 +574,25 @@ def conditional_process_examples(app, config):
         app.connect("autodoc-process-docstring", _process_autodoc_docstrings)
 
 
+def write_try_examples_runtime_config(app, exception):
+    """Add default runtime configuration file .try_examples.json.
+
+    These configuration options can be changed in the deployed docs without
+    rebuilding by replacing this file.
+    """
+    if exception is not None:
+        return
+
+    config = app.config.try_examples_default_runtime_config
+    if config is None:
+        return
+
+    output_dir = app.outdir
+    config_path = os.path.join(output_dir, ".try_examples.json")
+    with open(config_path, "w") as f:
+        json.dump(config, f, indent=4)
+
+
 def inited(app: Sphinx, config):
     # Create the content dir
     os.makedirs(os.path.join(app.srcdir, CONTENT_DIR), exist_ok=True)
@@ -648,6 +678,9 @@ def setup(app):
     # We need to build JupyterLite at the end, when all the content was created
     app.connect("build-finished", jupyterlite_build)
 
+    # Write default .try_examples.json after build finishes.
+    app.connect("build-finished", write_try_examples_runtime_config)
+
     # Config options
     app.add_config_value("jupyterlite_config", None, rebuild="html")
     app.add_config_value("jupyterlite_dir", app.srcdir, rebuild="html")
@@ -672,6 +705,11 @@ def setup(app):
         default=None,
         rebuild="html",
     )
+    app.add_config_value(
+        "try_examples_default_runtime_config",
+        default=None,
+        rebuild=None,
+    )
 
     # Initialize NotebookLite and JupyterLite directives
     app.add_node(