Doc: render the widgets in notebook

Author: unkcpz

docs/source/conf.py

@@ -16,6 +16,10 @@
 
 from aiidalab_widgets_base import __version__  # pylint: disable=wrong-import-position
 
+# work around unpickleable functions
+sys.path.append(str(Path(__file__).parent))
+from ipywidgets_docs_utils import jupyterlab_markdown_heading
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -27,7 +31,21 @@
     "myst_nb",
 ]
 
-nb_execution_mode = "off"
+myst_heading_anchors = 4
+myst_heading_slug_func = jupyterlab_markdown_heading
+
+nb_ipywidgets_js = {
+    "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js": {
+        "integrity": "sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=",
+        "crossorigin": "anonymous",
+    },
+    "https://cdn.jsdelivr.net/npm/@jupyter-widgets/html-manager@*/dist/embed-amd.js": {
+        "data-jupyter-widgets-cdn": "https://cdn.jsdelivr.net/npm/",
+        "crossorigin": "anonymous",
+    },
+}
+
+nb_execution_mode = "cache"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/source/ipywidgets_docs_utils.py

@@ -0,0 +1,7 @@
+def jupyterlab_markdown_heading(heading_text):
+    """Use JupyterLab-style anchors for a consistent authoring/viewing experience.
+
+    This _must_ be defined in an external file as local functions can't be asssigned
+    to config values, as they can't be pickled.
+    """
+    return heading_text.replace(" ", "-")

notebooks/viewers.ipynb

@@ -46,6 +46,7 @@
     "    'parameter 4' : [1, 2, 3],\n",
     "})\n",
     "vwr = viewer(p.store(), downloadable=True)\n",
+    "vwr.layout.width = '80%'\n",
     "display(vwr)"
    ]
   },