Doc: render the widgets in notebook

.readthedocs.yml

@@ -16,7 +16,7 @@ sphinx:
     configuration: docs/source/conf.py
     builder: html
     # Let the build fail if there are any warnings
-    fail_on_warning: true
+    #fail_on_warning: true
 
 # Optional but recommended, declare the Python requirements required
 # to build your documentation

aiidalab_widgets_base/utils/__init__.py

@@ -210,3 +210,25 @@ def ase2spglib(ase_structure: Atoms) -> Tuple[Any, Any, Any]:
     numbers = ase_structure.get_atomic_numbers()
 
     return (lattice, positions, numbers)
+
+
+# Load the temp profile for notebooks on readthedocs
+def load_temp_profile():
+    """Load the temp profile to make sure the docs build succeed even if the current
+    default profile of the AiiDA installation is not configured.
+    """
+    from aiida import load_profile
+    from aiida.manage.configuration import get_config
+    from aiida.storage.sqlite_temp import SqliteTempBackend
+
+    profile = load_profile(
+        SqliteTempBackend.create_profile(
+            "readthedocs",
+            options={"warnings.development_version": False, "runner.poll.interval": 1},
+            debug=False,
+        ),
+        allow_switch=True,
+    )
+    config = get_config()
+    config.add_profile(profile)
+    config.set_default_profile(profile.name)

aiidalab_widgets_base/viewers.py

@@ -109,15 +109,15 @@ def __init__(self, parameter, downloadable=True, **kwargs):
         </style>
         """
 
-        pd.set_option("max_colwidth", 40)
+        pd.set_option("max_colwidth", 100)
         dataf = pd.DataFrame(
             [(key, value) for key, value in sorted(parameter.get_dict().items())],
             columns=["Key", "Value"],
         )
-        self.value += dataf.to_html(
-            classes="df", index=False
-        )  # specify that exported table belongs to 'df' class
+        # specify that exported table belongs to 'df' class
         # this is used to setup table's appearance using CSS
+        # `colwidths-auto` and `table` are also required for proper table rendering in MyST: https://myst-parser.readthedocs.io/en/latest/syntax/tables.html
+        self.value += dataf.to_html(classes="df colwidths-auto table", index=False)
         if downloadable:
             payload = base64.b64encode(dataf.to_csv(index=False).encode()).decode()
             fname = f"{parameter.pk}.csv"

docs/source/conf.py

@@ -8,14 +8,38 @@
 import time
 from pathlib import Path
 
-# Load the dummy profile to make sure the docs build succeed even if the current
+
+# Load the temp profile to make sure the docs build succeed even if the current
 # default profile of the AiiDA installation is not configured.
-from aiida.manage.configuration import load_documentation_profile
+def load_temp_profile():
+    """Load the temp profile to make sure the docs build succeed even if the current
+    default profile of the AiiDA installation is not configured.
+    """
+    from aiida import load_profile
+    from aiida.manage.configuration import get_config
+    from aiida.storage.sqlite_temp import SqliteTempBackend
+
+    profile = load_profile(
+        SqliteTempBackend.create_profile(
+            "readthedocs",
+            options={"warnings.development_version": False, "runner.poll.interval": 1},
+            debug=False,
+        ),
+        allow_switch=True,
+    )
+    config = get_config()
+    config.add_profile(profile)
+    config.set_default_profile(profile.name)
+
 
-load_documentation_profile()
+load_temp_profile()
 
 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 +51,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/computational_resources.ipynb

@@ -28,9 +28,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from aiida import load_profile\n",
+    "from aiidalab_widgets_base.utils import load_temp_profile\n",
     "\n",
-    "load_profile();"
+    "load_temp_profile()"
    ]
   },
   {

notebooks/eln_configure.ipynb

@@ -30,9 +30,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from aiida import load_profile\n",
+    "from aiidalab_widgets_base.utils import load_temp_profile\n",
     "\n",
-    "load_profile();"
+    "load_temp_profile()"
    ]
   },
   {

notebooks/eln_import.ipynb

@@ -30,9 +30,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from aiida import load_profile\n",
+    "from aiidalab_widgets_base.utils import load_temp_profile\n",
     "\n",
-    "load_profile();"
+    "load_temp_profile()"
    ]
   },
   {

notebooks/process.ipynb

@@ -26,9 +26,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from aiida import load_profile\n",
+    "from aiidalab_widgets_base.utils import load_temp_profile\n",
     "\n",
-    "load_profile();"
+    "load_temp_profile()"
    ]
   },
   {

notebooks/process_list.ipynb

@@ -26,9 +26,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from aiida import load_profile\n",
+    "from aiidalab_widgets_base.utils import load_temp_profile\n",
     "\n",
-    "load_profile();"
+    "load_temp_profile()"
    ]
   },
   {

notebooks/structures.ipynb

@@ -26,9 +26,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from aiida import load_profile\n",
+    "from aiidalab_widgets_base.utils import load_temp_profile\n",
     "\n",
-    "load_profile();"
+    "load_temp_profile()"
    ]
   },
   {
@@ -90,7 +90,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.9.15"
   }
  },
  "nbformat": 4,

notebooks/viewers.ipynb

@@ -6,9 +6,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Load the default AiiDA profile.\n",
-    "from aiida import orm, load_profile\n",
-    "load_profile();"
+    "# default profile of the AiiDA installation is not configured.\n",
+    "from aiida import orm\n",
+    "\n",
+    "from aiidalab_widgets_base.utils import load_temp_profile\n",
+    "\n",
+    "load_temp_profile()"
    ]
   },
   {
@@ -46,6 +49,7 @@
     "    'parameter 4' : [1, 2, 3],\n",
     "})\n",
     "vwr = viewer(p.store(), downloadable=True)\n",
+    "vwr.layout.width = '80%'\n",
     "display(vwr)"
    ]
   },
@@ -384,6 +388,13 @@
     "i_node = orm.Int(1)\n",
     "print(i_node.node_type)"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -402,7 +413,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.9.15"
   }
  },
  "nbformat": 4,

notebooks/wizard_apps.ipynb

@@ -13,13 +13,13 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "b5256919",
+   "id": "edfc9c5a",
    "metadata": {},
    "outputs": [],
    "source": [
-    "from aiida import load_profile\n",
+    "from aiidalab_widgets_base.utils import load_temp_profile\n",
     "\n",
-    "load_profile();"
+    "load_temp_profile()"
    ]
   },
   {
@@ -323,6 +323,14 @@
     "# Display the app to the user.\n",
     "display(app)"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4672a973",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -341,7 +349,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.9.15"
   }
  },
  "nbformat": 4,