User-friendly error if py file has # %% comments with unexpected format

fixes #1188

Author: seeM

nbdev/doclinks.py

@@ -49,7 +49,10 @@ def _iter_py_cells(p):
     cells = p.read_text().split("\n# %% ")
     for cell in cells[1:]:
         top,code = cell.split('\n', 1)
-        nb,idx = top.split()
+        try: nb,idx = top.split()
+        except ValueError:
+            raise NotImplementedError(f"Unexpected format in '{p}' at cell:\n```\n# %% {cell.strip()}.\n```\n"
+                                      "The expected format is: '# %% {nb_path} {cell_idx}'.")
         nb_path = None if nb=='auto' else (p.parent/nb).resolve()  # NB paths are stored relative to .py file
         if code.endswith('\n'): code=code[:-1]
         yield AttrDict(nb=nb, idx=int(idx), code=code, nb_path=nb_path, py_path=p.resolve())

nbs/api/doclinks.ipynb

@@ -137,7 +137,10 @@
     "    cells = p.read_text().split(\"\\n# %% \")\n",
     "    for cell in cells[1:]:\n",
     "        top,code = cell.split('\\n', 1)\n",
-    "        nb,idx = top.split()\n",
+    "        try: nb,idx = top.split()\n",
+    "        except ValueError:\n",
+    "            raise NotImplementedError(f\"Unexpected format in '{p}' at cell:\\n```\\n# %% {cell.strip()}.\\n```\\n\"\n",
+    "                                      \"The expected format is: '# %% {nb_path} {cell_idx}'.\")\n",
     "        nb_path = None if nb=='auto' else (p.parent/nb).resolve()  # NB paths are stored relative to .py file\n",
     "        if code.endswith('\\n'): code=code[:-1]\n",
     "        yield AttrDict(nb=nb, idx=int(idx), code=code, nb_path=nb_path, py_path=p.resolve())"