refactor: simplify spec loading in docs with async and show loading errors

.github/workflows/test.yml

@@ -3,14 +3,9 @@ name: Test
 on:
   workflow_dispatch:
   pull_request:
-    paths-ignore:
-      - 'site/**'
   push:
     branches:
       - main
-    paths-ignore:
-      - 'site/**'
-      - 'yarn.lock'
 
 jobs:
   test:

site/Gemfile.lock

@@ -1,36 +1,44 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.8)
+    activesupport (7.1.3)
+      base64
+      bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
+      mutex_m
       tzinfo (~> 2.0)
-    addressable (2.8.5)
+    addressable (2.8.6)
       public_suffix (>= 2.0.2, < 6.0)
-    base64 (0.1.1)
+    base64 (0.2.0)
+    bigdecimal (3.1.6)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
     coffee-script-source (1.11.1)
     colorator (1.1.0)
     commonmarker (0.23.10)
-    concurrent-ruby (1.2.2)
+    concurrent-ruby (1.2.3)
+    connection_pool (2.4.1)
     dnsruby (1.70.0)
       simpleidn (~> 0.2.1)
+    drb (2.2.0)
+      ruby2_keywords
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     ethon (0.16.0)
       ffi (>= 1.15.0)
     eventmachine (1.2.7)
     execjs (2.9.1)
-    faraday (2.7.11)
-      base64
-      faraday-net_http (>= 2.0, < 3.1)
-      ruby2_keywords (>= 0.0.4)
-    faraday-net_http (3.0.2)
-    ffi (1.16.2)
+    faraday (2.9.0)
+      faraday-net_http (>= 2.0, < 3.2)
+    faraday-net_http (3.1.0)
+      net-http
+    ffi (1.16.3)
     forwardable-extended (2.6.0)
     gemoji (3.0.1)
     github-pages (228)
@@ -211,20 +219,23 @@ GEM
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
-    minitest (5.20.0)
-    nokogiri (1.15.4-arm64-darwin)
+    minitest (5.21.2)
+    mutex_m (0.2.0)
+    net-http (0.4.1)
+      uri
+    nokogiri (1.16.0-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.15.4-x86_64-darwin)
+    nokogiri (1.16.0-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.15.4-x86_64-linux)
+    nokogiri (1.16.0-x86_64-linux)
       racc (~> 1.4)
     octokit (4.25.1)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (4.0.7)
-    racc (1.7.1)
+    racc (1.7.3)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
@@ -245,20 +256,22 @@ GEM
       unf (~> 0.1.4)
     terminal-table (1.8.0)
       unicode-display_width (~> 1.1, >= 1.1.1)
-    typhoeus (1.4.0)
+    typhoeus (1.4.1)
       ethon (>= 0.9.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unf (0.1.4)
       unf_ext
-    unf_ext (0.0.8.2)
+    unf_ext (0.0.9.1)
     unicode-display_width (1.8.0)
+    uri (0.13.0)
     webrick (1.8.1)
 
 PLATFORMS
   arm64-darwin-20
   arm64-darwin-21
   arm64-darwin-22
+  arm64-darwin-23
   x86_64-darwin-19
   x86_64-darwin-20
   x86_64-linux

site/static/index.ts

@@ -51,8 +51,7 @@ selectAll('h2, h3, h4, h5, h6').each(function (this: d3.BaseType) {
 
 /* Documentation */
 function renderExample($target: Selection<any, any, any, any>, specText: string, figureOnly: boolean) {
-  $target.classed('example', true);
-  $target.text('');
+  $target.classed('example', true).text('');
 
   const vis = $target.append('div').attr('class', 'example-vis');
 
@@ -108,24 +107,25 @@ export function embedExample($target: any, spec: TopLevelSpec, actions = true, t
   return view;
 }
 
-function getSpec(el: d3.BaseType) {
+async function getSpec(el: d3.BaseType) {
   const sel = select(el);
   const name = sel.attr('data-name');
   const figureOnly = !!sel.attr('figure-only');
   if (name) {
     const dir = sel.attr('data-dir');
     const fullUrl = `${BASEURL}/examples/${dir ? `${dir}/` : ''}${name}.vl.json`;
 
-    fetch(fullUrl)
-      .then(response => {
-        response
-          .text()
-          .then(spec => {
-            renderExample(sel, spec, figureOnly);
-          })
-          .catch(console.error);
-      })
-      .catch(console.error);
+    try {
+      const spec = await (await fetch(fullUrl)).text();
+      renderExample(sel, spec, figureOnly);
+    } catch (e) {
+      sel
+        .html(
+          `Could not load spec: ${e}. Please report this issue on <a href="https://github.com/vega/vega-lite/issues/new/choose">GitHub</a>.`
+        )
+        .classed('error', true);
+      console.error(e);
+    }
   } else {
     console.error('No "data-name" specified to import examples from');
   }