Allow custom css for try_examples directive

- and update how try examples config is specified

Author: steppi

docs/_static/try_examples.css

@@ -0,0 +1,21 @@
+.try_examples_button {
+    background-color: #f7dc1e;
+    border: none;
+    padding: 5px 10px;
+    border-radius: 15px;
+    font-family: vibur;
+    font-size: larger;
+    box-shadow: 0 2px 5px rgba(108,108,108,0.2);
+}
+
+.try_examples_button:hover {
+    background-color: #fff221;
+    transform: scale(1.02);
+    box-shadow: 0 2px 5px rgba(0, 0, 0, 0.2);
+    cursor: pointer;
+}
+
+.try_examples_button_container {
+    display: flex;
+    justify-content: flex-end;
+}

jupyterlite_sphinx/jupyterlite_sphinx.js

@@ -78,22 +78,22 @@ window.tryExamplesHideIframe = (examplesContainerId, iframeParentContainerId) =>
 }
 
 
-window.loadTryExamplesConfig = async (ignoreFilePath) => {
+window.loadTryExamplesConfig = async (configFilePath) => {
     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 configFileUrl = `${configFilePath}?cb=${timestamp}`;
         const currentPageUrl = window.location.pathname;
 
-        const response = await fetch(ignoreFileUrl);
+        const response = await fetch(configFileUrl);
         if (!response.ok) {
             if (response.status === 404) {
                 // Try examples ignore file is not present.
-                console.log('Ignore file not found.');
+                console.log('try_examples config file not found.');
                 return;
             }
-            throw new Error(`Error fetching ${ignoreFilePath}`);
+            throw new Error(`Error fetching ${configFilePath}`);
         }
 
         const data = await response.json();

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -2,11 +2,8 @@
 import json
 from uuid import uuid4
 import shutil
-import tempfile
-from warnings import warn
 import glob
 import re
-import nbformat as nbf
 
 from pathlib import Path
 
@@ -19,7 +16,6 @@
 from docutils import nodes
 
 from sphinx.application import Sphinx
-from sphinx.ext.doctest import DoctestDirective
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.fileutil import copy_asset
 from sphinx.parsers import RSTParser
@@ -370,10 +366,7 @@ class TryExamplesDirective(SphinxDirective):
     option_spec = {
         "theme": directives.unchanged,
         "button_text": directives.unchanged,
-        "button_css": directives.unchanged,
-        "button_hover_css": directives.unchanged,
-        "button_horizontal_position": directives.unchanged,
-        "button_vertical_position": directives.unchanged,
+        "example_class": directives.unchanged,
         "min_height": directives.unchanged,
     }
 
@@ -387,26 +380,9 @@ def run(self):
         )
 
         button_text = self.options.pop("button_text", "Try it with Jupyterlite!")
-        button_css = self.options.pop("button_css", "")
-        button_hover_css = self.options.pop("button_hover_css", "")
-        button_horizontal_position = self.options.pop(
-            "button_horizontal_position", "right"
-        )
-        button_vertical_position = self.options.pop("button_vertical_position", "top")
+        example_class = self.options.pop("example_class", "")
         min_height = self.options.pop("min_height", "200px")
 
-        if button_horizontal_position not in ["left", "center", "right"]:
-            raise RuntimeError(
-                "try_examples directive expects button_horizontal_position to be one of"
-                f" 'left', 'center', or 'right', received {button_horizontal_position}."
-            )
-
-        if button_vertical_position not in ["bottom", "top"]:
-            raise RuntimeError(
-                "try_examples directive expects button_vertical_position to be one of"
-                f" 'top' or 'bottom', received {button_vertical_position}."
-            )
-
         # We need to get the relative path back to the documentation root from
         # whichever file the docstring content is in.
         docname = self.env.docname
@@ -454,7 +430,7 @@ def run(self):
         # Parent container (initially hidden)
         iframe_parent_container_div_start = (
             f'<div id="{iframe_parent_div_id}" '
-            f'class="try_examples_outer_container hidden">'
+            f'class="try_examples_outer_container {example_class} hidden">'
         )
 
         iframe_parent_container_div_end = "</div>"
@@ -487,51 +463,19 @@ def run(self):
         try_it_button_node = nodes.raw("", try_it_button_html, format="html")
 
         # Combine everything
-        if button_vertical_position == "top":
-            notebook_container_html = (
-                iframe_parent_container_div_start
-                + go_back_button_html
-                + iframe_container_div
-                + iframe_parent_container_div_end
-            )
-            content_container_node += try_it_button_node
-            content_container_node += content_node
-        else:
-            notebook_container_html = (
-                iframe_parent_container_div_start
-                + iframe_container_div
-                + go_back_button_html
-                + iframe_parent_container_div_end
-            )
-            content_container_node += content_node
-            content_container_node += try_it_button_node
-
-        notebook_container = nodes.raw("", notebook_container_html, format="html")
-
-        # Generate css for button based on options.
-        if button_css:
-            button_css = f".try_examples_button {{{button_css}}}"
-        if button_hover_css:
-            button_hover_css = f".try_examples_button:hover {{{button_hover_css}}}"
-
-        justify = {"left": "flex-start", "center": "center", "right": "flex-end"}[
-            button_horizontal_position
-        ]
-
-        button_container_css = (
-            ".try_examples_button_container {"
-            f"display: flex; justify-content: {justify}"
-            "}"
+        notebook_container_html = (
+            iframe_parent_container_div_start
+            + go_back_button_html
+            + iframe_container_div
+            + iframe_parent_container_div_end
         )
+        content_container_node += try_it_button_node
+        content_container_node += content_node
 
-        complete_button_css = button_css + button_hover_css + button_container_css
-
-        style_tag = nodes.raw(
-            "", f"<style>{complete_button_css}</style>", format="html"
-        )
+        notebook_container = nodes.raw("", notebook_container_html, format="html")
 
-        # Search cnofig file allowing for config changes without rebuilding docs.
-        config_path = os.path.join(relative_path_to_root, ".try_examples.json")
+        # Search config 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() {'
@@ -541,7 +485,7 @@ def run(self):
         )
         script_node = nodes.raw("", script_html, format="html")
 
-        return [content_container_node, notebook_container, style_tag, script_node]
+        return [content_container_node, notebook_container, script_node]
 
 
 def _process_docstring_examples(app, docname, source):
@@ -554,10 +498,7 @@ def _process_autodoc_docstrings(app, what, name, obj, options, lines):
     try_examples_options = {
         "theme": app.config.try_examples_global_theme,
         "button_text": app.config.try_examples_global_button_text,
-        "button_css": app.config.try_examples_global_button_css,
-        "button_hover_css": app.config.try_examples_global_button_hover_css,
-        "button_horizontal_position": app.config.try_examples_global_button_horizontal_position,
-        "button_vertical_position": app.config.try_examples_global_button_vertical_position,
+        "example_class": app.config.try_examples_global_example_class,
         "min_height": app.config.try_examples_global_min_height,
     }
     try_examples_options = {
@@ -574,25 +515,6 @@ 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)
@@ -678,9 +600,6 @@ 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")
@@ -689,27 +608,15 @@ def setup(app):
 
     app.add_config_value("global_enable_try_examples", default=False, rebuild=True)
     app.add_config_value("try_examples_global_theme", default=None, rebuild=True)
-    app.add_config_value("try_examples_global_button_css", default=None, rebuild="html")
-    app.add_config_value(
-        "try_examples_global_button_hover_css", default=None, rebuild="html"
-    )
-    app.add_config_value(
-        "try_examples_global_button_horizontal_position", default=None, rebuild="html"
-    )
     app.add_config_value(
-        "try_examples_global_button_vertical_position", default=None, rebuild="html"
+        "try_examples_global_example_class", default=None, rebuild="html"
     )
     app.add_config_value("try_examples_global_min_height", default=None, rebuild="html")
     app.add_config_value(
         "try_examples_global_button_text",
         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(
@@ -768,6 +675,11 @@ def setup(app):
 
     app.add_js_file("jupyterlite_sphinx.js")
 
+    # Copy optional try examples runtime config if it exists.
+    try_examples_config_path = Path(app.srcdir) / "try_examples.json"
+    if try_examples_config_path.exists():
+        copy_asset(str(try_examples_config_path), app.outdir)
+
 
 def search_params_parser(search_params: str) -> str:
     pattern = re.compile(r"^\[(?:\s*[\"']{1}([^=\s\,&=\?\/]+)[\"']{1}\s*\,?)+\]$")