From 02845464d8c8ce2996112552f933b00a8d9936b9 Mon Sep 17 00:00:00 2001
From: "A bot of @njzjz" <48687836+njzjz-bot@users.noreply.github.com>
Date: Thu, 20 Aug 2026 02:08:42 +0800
Subject: [PATCH] fix(docs): make JupyterLite demo data reliably accessible

Replay #945 on the current LMDB plugin layout so core dpdata imports do not require LMDB-only dependencies. Stage the online notebook and OUTCAR together for robust xeus content mounting, keep the demo portable across JupyterLite working directories, and remove the duplicate notebook heading.

Coding agent: ChatGPT
Model: GPT-5.6 Sol
---
 .github/workflows/test_import.yml | 20 ++++++++++++++++++++
 docs/conf.py                      |  3 +++
 docs/nb/try_dpdata.ipynb          | 14 ++++++--------
 docs/try_dpdata.rst               |  2 +-
 dpdata/plugins/lmdb.py            | 18 +++++++++++++++++-
 5 files changed, 47 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/test_import.yml b/.github/workflows/test_import.yml
index 676a2f0c2..27912fa3e 100644
--- a/.github/workflows/test_import.yml
+++ b/.github/workflows/test_import.yml
@@ -33,3 +33,23 @@ jobs:
         assert loaded.formula == system.formula
         assert loaded.get_nframes() == system.get_nframes()
         PY
+    - name: Test core import without LMDB dependencies
+      run: |
+        python -m pip uninstall -y lmdb msgpack
+        python - <<'PY'
+        import dpdata
+
+        system = dpdata.System(
+            "tests/poscars/POSCAR.h2o.md", fmt="vasp/poscar"
+        )
+        assert system.get_nframes() == 1
+
+        try:
+            dpdata.System("missing.lmdb", fmt="lmdb")
+        except ModuleNotFoundError as exc:
+            assert "lmdb" in str(exc)
+        else:
+            raise AssertionError(
+                "LMDB format should require its backend dependencies"
+            )
+        PY
diff --git a/docs/conf.py b/docs/conf.py
index a4d82c250..aeedc95d5 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -216,3 +216,6 @@ def setup(app):
 jupyterlite_contents = "./nb"
 jupyterlite_bind_ipynb_suffix = False
 jupyterlite_silence = False
+jupyterlite_build_command_options = {
+    "XeusAddon.mount_jupyterlite_content": True,
+}
diff --git a/docs/nb/try_dpdata.ipynb b/docs/nb/try_dpdata.ipynb
index 1a0a73280..8ac85b430 100644
--- a/docs/nb/try_dpdata.ipynb
+++ b/docs/nb/try_dpdata.ipynb
@@ -1,12 +1,5 @@
 {
  "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Try dpdata online"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -15,6 +8,8 @@
    "source": [
     "from __future__ import annotations\n",
     "\n",
+    "from pathlib import Path\n",
+    "\n",
     "import dpdata"
    ]
   },
@@ -24,7 +19,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "system = dpdata.LabeledSystem(\"OUTCAR\", fmt=\"vasp/outcar\", type_map=[\"O\", \"H\"])"
+    "outcar = Path(\"OUTCAR\")\n",
+    "if not outcar.is_file():\n",
+    "    outcar = Path(\"nb/OUTCAR\")\n",
+    "system = dpdata.LabeledSystem(outcar, fmt=\"vasp/outcar\", type_map=[\"O\", \"H\"])"
    ]
   },
   {
diff --git a/docs/try_dpdata.rst b/docs/try_dpdata.rst
index fba69153c..ec085c217 100644
--- a/docs/try_dpdata.rst
+++ b/docs/try_dpdata.rst
@@ -1,4 +1,4 @@
 Try dpdata online
 =================
 
-.. retrolite:: nb/try_dpdata.ipynb
+.. notebooklite:: nb/try_dpdata.ipynb
diff --git a/dpdata/plugins/lmdb.py b/dpdata/plugins/lmdb.py
index aa4836445..2f8f3a4d5 100644
--- a/dpdata/plugins/lmdb.py
+++ b/dpdata/plugins/lmdb.py
@@ -1,7 +1,23 @@
 from __future__ import annotations
 
 from dpdata.format import Format
-from dpdata.formats.deepmd.lmdb.format import LMDBFormat
+
+try:
+    from dpdata.formats.deepmd.lmdb.format import LMDBFormat
+except ModuleNotFoundError as exc:
+    if exc.name not in {"lmdb", "msgpack"}:
+        raise
+
+    _lmdb_import_error = exc
+
+    class LMDBFormat(Format):
+        """Placeholder used when the LMDB backend dependencies are unavailable."""
+
+        def __init__(self, *args, **kwargs) -> None:
+            raise ModuleNotFoundError(
+                "The deepmd/lmdb format requires the 'lmdb' and 'msgpack' packages."
+            ) from _lmdb_import_error
+
 
 # Canonical name; ``lmdb`` is kept as a backward-compatible alias.
 Format.register("deepmd/lmdb")(LMDBFormat)