add gallery to landing page

sphinx-panels was broken so we switch to sphinx-design instead

Author: rmorshea

docs/source/_exts/interactive_widget.py

@@ -1,7 +1,7 @@
 import os
 
 from docutils.nodes import raw
-from docutils.parsers.rst import Directive
+from docutils.parsers.rst import Directive, directives
 from sphinx.application import Sphinx
 
 
@@ -15,6 +15,10 @@ class IteractiveWidget(Directive):
     required_arguments = 1
     _next_id = 0
 
+    option_spec = {
+        "no-activate-button": directives.flag,
+    }
+
     def run(self):
         IteractiveWidget._next_id += 1
         container_id = f"idom-widget-{IteractiveWidget._next_id}"
@@ -27,7 +31,12 @@ def run(self):
                     <div id="{container_id}" class="interactive widget-container center-content" style="" />
                     <script type="module">
                         import {{ mountWidgetExample }} from "{_IDOM_STATIC_HOST}/_static/custom.js";
-                        mountWidgetExample("{container_id}", "{view_id}", "{_IDOM_EXAMPLE_HOST}");
+                        mountWidgetExample(
+                            "{container_id}",
+                            "{view_id}",
+                            "{_IDOM_EXAMPLE_HOST}",
+                            {"false" if "no-activate-button" in self.options else "true"},
+                        );
                     </script>
                 </div>
                 """,

docs/source/_exts/widget_example.py

@@ -4,7 +4,7 @@
 from docutils.statemachine import StringList
 from sphinx.application import Sphinx
 from sphinx.util.docutils import SphinxDirective
-from sphinx_panels.tabs import TabbedDirective
+from sphinx_design.tabs import TabSetDirective
 
 
 here = Path(__file__).parent
@@ -17,7 +17,10 @@ class WidgetExample(SphinxDirective):
     required_arguments = 1
     _next_id = 0
 
-    option_spec = {"linenos": directives.flag}
+    option_spec = {
+        "linenos": directives.flag,
+        "live-example-is-default-tab": directives.flag,
+    }
 
     def run(self):
         example_name = self.arguments[0]
@@ -30,45 +33,39 @@ def run(self):
                 f"Missing example file named {py_ex_path} referenced by document {src_file}:{line_num}"
             )
 
-        py_code_tab = TabbedDirective(
-            "WidgetExample",
-            ["Python Code"],
-            {},
-            _literal_include_py_lines(
+        labeled_tab_items = {
+            "Python Code": _literal_include_py(
                 name=example_name,
                 linenos=show_linenos,
             ),
-            self.lineno - 1,
-            self.content_offset,
-            "",
-            self.state,
-            self.state_machine,
-        ).run()
+            "Live Example": _interactive_widget(
+                name=example_name,
+                use_activate_button="live-example-is-default-tab" not in self.options,
+            ),
+        }
 
         if (examples / f"{example_name}.js").exists():
-            js_code_tab = TabbedDirective(
-                "WidgetExample",
-                ["Javascript Code"],
-                {},
-                _literal_include_js_lines(
-                    name=example_name,
-                    linenos=show_linenos,
-                ),
-                self.lineno - 1,
-                self.content_offset,
-                "",
-                self.state,
-                self.state_machine,
-            ).run()
-        else:
-            js_code_tab = []
-
-        example_tab = TabbedDirective(
+            labeled_tab_items["Javascript Code"] = _literal_include_js(
+                name=example_name,
+                linenos=show_linenos,
+            )
+
+        tab_label_order = (
+            ["Live Example", "Python Code", "Javascript Code"]
+            if "live-example-is-default-tab" in self.options
+            else ["Python Code", "Javascript Code", "Live Example"]
+        )
+
+        return TabSetDirective(
             "WidgetExample",
-            ["Live Example"],
+            [],
             {},
-            _string_to_nested_lines(
-                _interactive_widget_template.format(name=example_name)
+            _make_tab_items(
+                [
+                    (label, labeled_tab_items[label])
+                    for label in tab_label_order
+                    if label in labeled_tab_items
+                ]
             ),
             self.lineno - 1,
             self.content_offset,
@@ -77,33 +74,52 @@ def run(self):
             self.state_machine,
         ).run()
 
-        return py_code_tab + js_code_tab + example_tab
 
-
-def _literal_include_py_lines(name, linenos):
-    return _string_to_nested_lines(
-        _literal_include_template.format(
-            name=name,
-            ext="py",
-            language="python",
-            linenos=":linenos:" if linenos else "",
+def _make_tab_items(labeled_content_tuples):
+    tab_items = ""
+    for label, content in labeled_content_tuples:
+        tab_items += _tab_item_template.format(
+            label=label,
+            content=content.replace("\n", "\n    "),
         )
+    return _string_to_nested_lines(tab_items)
+
+
+def _literal_include_py(name, linenos):
+    return _literal_include_template.format(
+        name=name,
+        ext="py",
+        language="python",
+        linenos=":linenos:" if linenos else "",
     )
 
 
-def _literal_include_js_lines(name, linenos):
-    return _string_to_nested_lines(
-        _literal_include_template.format(
-            name=name,
-            ext="js",
-            language="javascript",
-            linenos=":linenos:" if linenos else "",
-        )
+def _literal_include_js(name, linenos):
+    return _literal_include_template.format(
+        name=name,
+        ext="js",
+        language="javascript",
+        linenos=":linenos:" if linenos else "",
     )
 
 
+def _interactive_widget(name, use_activate_button):
+    return _interactive_widget_template.format(
+        name=name,
+        activate_button_opt="" if use_activate_button else ":no-activate-button:",
+    )
+
+
+_tab_item_template = """
+.. tab-item:: {label}
+
+    {content}
+"""
+
+
 _interactive_widget_template = """
 .. interactive-widget:: {name}
+    {activate_button_opt}
 """
 
 

docs/source/_static/css/interactive-widget.css

@@ -19,13 +19,13 @@
   color: #ffffff !important;
   text-transform: uppercase;
   text-decoration: none;
-  background: #3980b9;
-  border: 2px solid #3980b9 !important;
+  background: #526cfe;
+  border: 2px solid #526cfe !important;
   transition: all 0.1s ease 0s;
   box-shadow: 0 5px 10px var(--color-foreground-border);
 }
 .enable-widget-button:hover {
-  color: #3980b9 !important;
+  color: #526cfe !important;
   background: #ffffff;
   transition: all 0.1s ease 0s;
 }

docs/source/_static/css/larger-headings.css

@@ -5,7 +5,6 @@ h4,
 h5,
 h6 {
   margin-top: 2em !important;
-  margin-bottom: 0 !important;
   font-weight: 900 !important;
 }
 

docs/source/_static/custom.js

@@ -1884,12 +1884,30 @@ const HTTP_PROTO = LOC.protocol;
 const WS_PROTO = HTTP_PROTO === "https:" ? "wss:" : "ws:";
 const IDOM_MODULES_PATH = "/_modules";
 
-function mountWidgetExample(mountID, viewID, idomServerHost) {
-  const idom_url = "//" + (idomServerHost || LOC.host);
-  const http_idom_url = HTTP_PROTO + idom_url;
-  const ws_idom_url = WS_PROTO + idom_url;
+function mountWidgetExample(
+  mountID,
+  viewID,
+  idomServerHost,
+  useActivateButton
+) {
+  const idomUrl  = "//" + (idomServerHost || LOC.host);
+  const httpIdomUrl = HTTP_PROTO + idomUrl ;
+  const wsIdomUrl = WS_PROTO + idomUrl ;
 
   const mountEl = document.getElementById(mountID);
+
+  console.log(useActivateButton);
+
+  if (!useActivateButton) {
+    mountLayoutWithWebSocket(
+      mountEl,
+      wsIdomUrl + `/_idom/stream?view_id=${viewID}`,
+      (source, sourceType) =>
+        loadImportSource(httpIdomUrl, source, sourceType)
+    );
+    return;
+  }
+
   const enableWidgetButton = document.createElement("button");
   enableWidgetButton.appendChild(document.createTextNode("Enable Widget"));
   enableWidgetButton.setAttribute("class", "enable-widget-button");
@@ -1901,9 +1919,9 @@ function mountWidgetExample(mountID, viewID, idomServerHost) {
         mountEl.setAttribute("class", "interactive widget-container");
         mountLayoutWithWebSocket(
           mountEl,
-          ws_idom_url + `/_idom/stream?view_id=${viewID}`,
+          wsIdomUrl + `/_idom/stream?view_id=${viewID}`,
           (source, sourceType) =>
-            loadImportSource(http_idom_url, source, sourceType)
+            loadImportSource(httpIdomUrl, source, sourceType)
         );
       }
     })

docs/source/conf.py

@@ -54,9 +54,9 @@
     "sphinx.ext.extlinks",
     "sphinx.ext.autosectionlabel",
     # third party extensions
-    "sphinx_panels",
     "sphinx_copybutton",
     "sphinx_reredirects",
+    "sphinx_design",
     # custom extensions
     "async_doctest",
     "autogen_api_docs",

docs/source/custom_js/src/index.js

@@ -5,12 +5,30 @@ const HTTP_PROTO = LOC.protocol;
 const WS_PROTO = HTTP_PROTO === "https:" ? "wss:" : "ws:";
 const IDOM_MODULES_PATH = "/_modules";
 
-export function mountWidgetExample(mountID, viewID, idomServerHost) {
-  const idom_url = "//" + (idomServerHost || LOC.host);
-  const http_idom_url = HTTP_PROTO + idom_url;
-  const ws_idom_url = WS_PROTO + idom_url;
+export function mountWidgetExample(
+  mountID,
+  viewID,
+  idomServerHost,
+  useActivateButton
+) {
+  const idomUrl  = "//" + (idomServerHost || LOC.host);
+  const httpIdomUrl = HTTP_PROTO + idomUrl ;
+  const wsIdomUrl = WS_PROTO + idomUrl ;
 
   const mountEl = document.getElementById(mountID);
+
+  console.log(useActivateButton);
+
+  if (!useActivateButton) {
+    mountLayoutWithWebSocket(
+      mountEl,
+      wsIdomUrl + `/_idom/stream?view_id=${viewID}`,
+      (source, sourceType) =>
+        loadImportSource(httpIdomUrl, source, sourceType)
+    );
+    return;
+  }
+
   const enableWidgetButton = document.createElement("button");
   enableWidgetButton.appendChild(document.createTextNode("Enable Widget"));
   enableWidgetButton.setAttribute("class", "enable-widget-button");
@@ -22,9 +40,9 @@ export function mountWidgetExample(mountID, viewID, idomServerHost) {
         mountEl.setAttribute("class", "interactive widget-container");
         mountLayoutWithWebSocket(
           mountEl,
-          ws_idom_url + `/_idom/stream?view_id=${viewID}`,
+          wsIdomUrl + `/_idom/stream?view_id=${viewID}`,
           (source, sourceType) =>
-            loadImportSource(http_idom_url, source, sourceType)
+            loadImportSource(httpIdomUrl, source, sourceType)
         );
       }
     })

docs/source/examples/play_audio_sound.py renamed to docs/source/examples/audio_player.py

@@ -64,7 +64,7 @@ async def animate():
         {
             "data": data,
             "style": {
-                "parent": {"width": "500px"},
+                "parent": {"width": "100%"},
                 "data": {"stroke": "royalblue"},
             },
         }

docs/source/examples/simple_dashboard.py

@@ -1,8 +1,7 @@
 Getting Started
 ===============
 
-Let's look at the example that you may have seen
-:ref:`at a glance <At a Glance>` on the homepage:
+Let's break down the following example:
 
 .. example:: slideshow
     :linenos:

docs/source/getting-started.rst

@@ -59,4 +59,4 @@ to demonstrate this is the ``currentTime`` attribute of ``audio`` and ``video``
 elements. Normally this would be accessible via ``event.target.currenTime``, but here
 it's simply passed in under the key ``currentTime``:
 
-.. example:: play_audio_sound
+.. example:: audio_player