fixes #1440

jph00 · jph00 · commit 5c0ee8c29f11 · 2024-08-27T16:47:50.000+10:00
diff --git a/nbdev/_modidx.py b/nbdev/_modidx.py
@@ -71,6 +71,7 @@
                                 'nbdev.doclinks.nbglob_cli': ('api/doclinks.html#nbglob_cli', 'nbdev/doclinks.py'),
                                 'nbdev.doclinks.patch_name': ('api/doclinks.html#patch_name', 'nbdev/doclinks.py')},
             'nbdev.export': { 'nbdev.export.ExportModuleProc': ('api/export.html#exportmoduleproc', 'nbdev/export.py'),
+                              'nbdev.export.ExportModuleProc.__call__': ('api/export.html#exportmoduleproc.__call__', 'nbdev/export.py'),
                               'nbdev.export.ExportModuleProc._default_exp_': ( 'api/export.html#exportmoduleproc._default_exp_',
                                                                                'nbdev/export.py'),
                               'nbdev.export.ExportModuleProc._export_': ('api/export.html#exportmoduleproc._export_', 'nbdev/export.py'),
diff --git a/nbdev/clean.py b/nbdev/clean.py
@@ -1,3 +1,5 @@
+"""Strip superfluous metadata from notebooks"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/11_clean.ipynb.
 
 # %% auto 0
diff --git a/nbdev/cli.py b/nbdev/cli.py
@@ -1,3 +1,5 @@
+"""CLI commands"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/13_cli.ipynb.
 
 # %% ../nbs/api/13_cli.ipynb 2
diff --git a/nbdev/config.py b/nbdev/config.py
@@ -1,16 +1,11 @@
-"""Read and write nbdev's `settings.ini` file.
-`get_config` is the main function for reading settings."""
+"""Configuring nbdev and bootstrapping notebook export"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/01_config.ipynb.
 
 # %% auto 0
 __all__ = ['nbdev_create_config', 'get_config', 'config_key', 'create_output', 'show_src', 'update_version', 'add_init',
            'write_cells']
 
-# %% ../nbs/api/01_config.ipynb
-_doc_ = """Read and write nbdev's `settings.ini` file.
-`get_config` is the main function for reading settings."""
-
 # %% ../nbs/api/01_config.ipynb
 from datetime import datetime
 from fastcore.docments import *
@@ -255,7 +250,7 @@ def add_init(path=None):
 def write_cells(cells, hdr, file, offset=0, cell_number=True):
     "Write `cells` to `file` along with header `hdr` starting at index `offset` (mainly for nbdev internal use)."
     for cell in cells:
-        if cell.source.strip():
+        if cell.cell_type=='code' and cell.source.strip():
             idx = f" {cell.idx_+offset}" if cell_number else ""
             file.write(f'\n\n{hdr}{idx}\n{cell.source}')
 
diff --git a/nbdev/doclinks.py b/nbdev/doclinks.py
@@ -1,3 +1,5 @@
+"""Generating a documentation index from a module"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/05_doclinks.ipynb.
 
 # %% auto 0
diff --git a/nbdev/export.py b/nbdev/export.py
@@ -1,3 +1,5 @@
+"""Exporting a notebook to a library"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/04_export.ipynb.
 
 # %% auto 0
@@ -24,6 +26,10 @@ def _exporti_(self, cell, exp_to=None): self.modules[ifnone(exp_to, '#')].append
     def _export_(self, cell, exp_to=None):
         self._exporti_(cell, exp_to)
         self.in_all[ifnone(exp_to, '#')].append(cell)
+    def __call__(self, cell):
+        src = cell.source
+        if not src: return
+        if cell.cell_type=='markdown' and src.startswith('# '): self.modules['#'].append(cell)
     _exports_=_export_
 
 # %% ../nbs/api/04_export.ipynb
@@ -67,12 +73,13 @@ def nb_export(nbname, lib_path=None, procs=None, debug=False, mod_maker=ModuleMa
     nb = NBProcessor(nbname, [exp]+L(procs), debug=debug)
     nb.process()
     for mod,cells in exp.modules.items():
-        all_cells = exp.in_all[mod]
-        nm = ifnone(name, getattr(exp, 'default_exp', None) if mod=='#' else mod)
-        if not nm:
-            warn(f"Notebook '{nbname}' uses `#|export` without `#|default_exp` cell.\n"
-                 "Note nbdev2 no longer supports nbdev1 syntax. Run `nbdev_migrate` to upgrade.\n"
-                 "See https://nbdev.fast.ai/getting_started.html for more information.")
-            return
-        mm = mod_maker(dest=lib_path, name=nm, nb_path=nbname, is_new=bool(name) or mod=='#')
-        mm.make(cells, all_cells, lib_path=lib_path)
+        if first(1 for o in cells if o.cell_type=='code'):
+            all_cells = exp.in_all[mod]
+            nm = ifnone(name, getattr(exp, 'default_exp', None) if mod=='#' else mod)
+            if not nm:
+                warn(f"Notebook '{nbname}' uses `#|export` without `#|default_exp` cell.\n"
+                     "Note nbdev2 no longer supports nbdev1 syntax. Run `nbdev_migrate` to upgrade.\n"
+                     "See https://nbdev.fast.ai/getting_started.html for more information.")
+                return
+            mm = mod_maker(dest=lib_path, name=nm, nb_path=nbname, is_new=bool(name) or mod=='#')
+            mm.make(cells, all_cells, lib_path=lib_path)
diff --git a/nbdev/frontmatter.py b/nbdev/frontmatter.py
@@ -1,3 +1,5 @@
+"""A YAML and formatted-markdown frontmatter processor"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/09_frontmatter.ipynb.
 
 # %% auto 0
diff --git a/nbdev/maker.py b/nbdev/maker.py
@@ -1,3 +1,5 @@
+"""Create one or more modules from selected notebook cells"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/02_maker.ipynb.
 
 # %% ../nbs/api/02_maker.ipynb 1
@@ -175,13 +177,13 @@ def _import2relative(cells, lib_name=None):
 
 # %% ../nbs/api/02_maker.ipynb
 def _retr_mdoc(cells):
-    "Search for `_doc_` variable, used to create module docstring"
-    trees = L(cells).map(NbCell.parsed_).concat()
-    for o in trees:
-        if isinstance(o, _assign_types) and getattr(_targets(o)[0],'id',None)=='_doc_':
-            v = try_attrs(o.value, 'value', 's') # py37 uses `ast.Str.s`
-            return f'"""{v}"""\n\n' 
-    return ""
+    "Search for md meta quote line, used to create module docstring"
+    md1 = first(o for o in cells if o.cell_type=='markdown' and o.source.startswith('# '))
+    if not md1: return ''
+    summ = first(o for o in md1.source.splitlines() if o.startswith('> '))
+    if not summ: return ''
+    summ = summ.lstrip('> ').strip()
+    return f'"""{summ}"""\n\n' if summ else ''
 
 # %% ../nbs/api/02_maker.ipynb
 @patch
diff --git a/nbdev/merge.py b/nbdev/merge.py
@@ -1,3 +1,5 @@
+"""Fix merge conflicts in jupyter notebooks"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/07_merge.ipynb.
 
 # %% auto 0
diff --git a/nbdev/migrate.py b/nbdev/migrate.py
@@ -1,3 +1,5 @@
+"""Utilities for migrating to nbdev"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/16_migrate.ipynb.
 
 # %% auto 0
diff --git a/nbdev/process.py b/nbdev/process.py
@@ -1,3 +1,5 @@
+"""A notebook processor"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/03_process.ipynb.
 
 # %% auto 0
diff --git a/nbdev/processors.py b/nbdev/processors.py
@@ -1,3 +1,5 @@
+"""Some processors for NBProcessor"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/10_processors.ipynb.
 
 # %% auto 0
diff --git a/nbdev/qmd.py b/nbdev/qmd.py
@@ -1,3 +1,5 @@
+"""Basic qmd generation helpers (experimental)"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/15_qmd.ipynb.
 
 # %% ../nbs/api/15_qmd.ipynb 2
diff --git a/nbdev/quarto.py b/nbdev/quarto.py
@@ -1,3 +1,5 @@
+"""Install and interact with Quarto from nbdev"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/14_quarto.ipynb.
 
 # %% ../nbs/api/14_quarto.ipynb 3
diff --git a/nbdev/release.py b/nbdev/release.py
@@ -1,3 +1,5 @@
+"""Auto-generated tagged releases and release notes from GitHub issues"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/18_release.ipynb.
 
 # %% auto 0
diff --git a/nbdev/serve.py b/nbdev/serve.py
@@ -1,3 +1,5 @@
+"""A parallel ipynb processor (experimental)"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/17_serve.ipynb.
 
 # %% auto 0
diff --git a/nbdev/showdoc.py b/nbdev/showdoc.py
@@ -1,3 +1,5 @@
+"""Display symbol documentation in notebook and website"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/08_showdoc.ipynb.
 
 # %% ../nbs/api/08_showdoc.ipynb 2
diff --git a/nbdev/sync.py b/nbdev/sync.py
@@ -1,3 +1,5 @@
+"""Propagate small changes in the library back to notebooks"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/06_sync.ipynb.
 
 # %% auto 0
diff --git a/nbdev/test.py b/nbdev/test.py
@@ -1,3 +1,5 @@
+"""Run unit tests on notebooks in parallel"""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/12_test.ipynb.
 
 # %% auto 0
diff --git a/nbs/api/01_config.ipynb b/nbs/api/01_config.ipynb
@@ -20,17 +20,6 @@
     "#|default_exp config"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "#|export\n",
-    "_doc_ = \"\"\"Read and write nbdev's `settings.ini` file.\n",
-    "`get_config` is the main function for reading settings.\"\"\""
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -739,7 +728,7 @@
     "def write_cells(cells, hdr, file, offset=0, cell_number=True):\n",
     "    \"Write `cells` to `file` along with header `hdr` starting at index `offset` (mainly for nbdev internal use).\"\n",
     "    for cell in cells:\n",
-    "        if cell.source.strip():\n",
+    "        if cell.cell_type=='code' and cell.source.strip():\n",
     "            idx = f\" {cell.idx_+offset}\" if cell_number else \"\"\n",
     "            file.write(f'\\n\\n{hdr}{idx}\\n{cell.source}')"
    ]
diff --git a/nbs/api/02_maker.ipynb b/nbs/api/02_maker.ipynb
@@ -237,7 +237,7 @@
     }
    ],
    "source": [
-    "mm = ModuleMaker(dest='tmp', name='test.testing', nb_path=Path.cwd()/'01_export.ipynb', is_new=True)\n",
+    "mm = ModuleMaker(dest='tmp', name='test.testing', nb_path=Path.cwd()/'04_export.ipynb', is_new=True)\n",
     "mm.fname"
    ]
   },
@@ -469,13 +469,13 @@
    "source": [
     "#|export\n",
     "def _retr_mdoc(cells):\n",
-    "    \"Search for `_doc_` variable, used to create module docstring\"\n",
-    "    trees = L(cells).map(NbCell.parsed_).concat()\n",
-    "    for o in trees:\n",
-    "        if isinstance(o, _assign_types) and getattr(_targets(o)[0],'id',None)=='_doc_':\n",
-    "            v = try_attrs(o.value, 'value', 's') # py37 uses `ast.Str.s`\n",
-    "            return f'\"\"\"{v}\"\"\"\\n\\n' \n",
-    "    return \"\""
+    "    \"Search for md meta quote line, used to create module docstring\"\n",
+    "    md1 = first(o for o in cells if o.cell_type=='markdown' and o.source.startswith('# '))\n",
+    "    if not md1: return ''\n",
+    "    summ = first(o for o in md1.source.splitlines() if o.startswith('> '))\n",
+    "    if not summ: return ''\n",
+    "    summ = summ.lstrip('> ').strip()\n",
+    "    return f'\"\"\"{summ}\"\"\"\\n\\n' if summ else ''"
    ]
   },
   {
@@ -485,8 +485,8 @@
    "outputs": [],
    "source": [
     "#|hide\n",
-    "c = make_code_cells(\"a = 'b'\\n_doc_ = 'hi'\")\n",
-    "test_eq(_retr_mdoc(c), '\"\"\"hi\"\"\"\\n\\n')"
+    "nb = read_nb('02_maker.ipynb')\n",
+    "test_eq(_retr_mdoc(nb.cells), '\"\"\"Create one or more modules from selected notebook cells\"\"\"\\n\\n')"
    ]
   },
   {
@@ -532,24 +532,19 @@
      "data": {
       "text/markdown": [
        "```python\n",
-       "\"\"\"module docstring here\"\"\"\n",
-       "\n",
-       "# AUTOGENERATED! DO NOT EDIT! File to edit: ../../01_export.ipynb.\n",
+       "# AUTOGENERATED! DO NOT EDIT! File to edit: ../../04_export.ipynb.\n",
        "\n",
-       "# %% ../../01_export.ipynb 0\n",
+       "# %% ../../04_export.ipynb 0\n",
        "from __future__ import print_function\n",
        "\n",
        "# %% auto 0\n",
-       "__all__ = ['a']\n",
-       "\n",
-       "# %% ../../01_export.ipynb 1\n",
-       "_doc_ = 'module docstring here'\n",
+       "__all__ = ['b']\n",
        "\n",
-       "# %% ../../01_export.ipynb 2\n",
+       "# %% ../../04_export.ipynb\n",
        "#|export\n",
        "def a(): ...\n",
        "\n",
-       "# %% ../../01_export.ipynb 3\n",
+       "# %% ../../04_export.ipynb\n",
        "def b(): ...\n",
        "\n",
        "```"
@@ -565,7 +560,6 @@
    ],
    "source": [
     "cells = make_code_cells(\"from __future__ import print_function\",\n",
-    "                        \"_doc_ = 'module docstring here'\",\n",
     "                        \"#|export\\ndef a(): ...\", \"def b(): ...\")\n",
     "mm.make(cells, L([cells[2]]))\n",
     "show_src(Path('tmp/test/testing.py').read_text(encoding='utf-8'))"
@@ -617,14 +611,14 @@
        "```python\n",
        "# AUTOGENERATED! DO NOT EDIT! File to edit: ../../01_export.ipynb.\n",
        "\n",
-       "# %% ../../01_export.ipynb 0\n",
+       "# %% ../../01_export.ipynb\n",
        "from __future__ import print_function\n",
        "\n",
-       "# %% ../../01_export.ipynb 1\n",
+       "# %% ../../01_export.ipynb\n",
        "#|export\n",
        "def a(): ...\n",
        "\n",
-       "# %% ../../01_export.ipynb 2\n",
+       "# %% ../../01_export.ipynb\n",
        "#|export\n",
        "class A:\n",
        "\n",
@@ -678,7 +672,7 @@
    "outputs": [],
    "source": [
     "c2 = make_code_cells(\"def c(): ...\", \"def d(): ...\")\n",
-    "mm = ModuleMaker(dest='tmp', name='test.testing', nb_path=Path.cwd()/'01_export.ipynb', is_new=False)\n",
+    "mm = ModuleMaker(dest='tmp', name='test.testing', nb_path=Path.cwd()/'04_export.ipynb', is_new=False)\n",
     "mm.make(c2, c2)"
    ]
   },
@@ -691,30 +685,25 @@
      "data": {
       "text/markdown": [
        "```python\n",
-       "\"\"\"module docstring here\"\"\"\n",
+       "# AUTOGENERATED! DO NOT EDIT! File to edit: ../../04_export.ipynb.\n",
        "\n",
-       "# AUTOGENERATED! DO NOT EDIT! File to edit: ../../01_export.ipynb.\n",
-       "\n",
-       "# %% ../../01_export.ipynb 0\n",
+       "# %% ../../04_export.ipynb 0\n",
        "from __future__ import print_function\n",
        "\n",
        "# %% auto 0\n",
-       "__all__ = ['a', 'c', 'd']\n",
-       "\n",
-       "# %% ../../01_export.ipynb 1\n",
-       "_doc_ = 'module docstring here'\n",
+       "__all__ = ['b', 'c', 'd']\n",
        "\n",
-       "# %% ../../01_export.ipynb 2\n",
+       "# %% ../../04_export.ipynb\n",
        "#|export\n",
        "def a(): ...\n",
        "\n",
-       "# %% ../../01_export.ipynb 3\n",
+       "# %% ../../04_export.ipynb\n",
        "def b(): ...\n",
        "\n",
-       "# %% ../../01_export.ipynb 0\n",
+       "# %% ../../04_export.ipynb 0\n",
        "def c(): ...\n",
        "\n",
-       "# %% ../../01_export.ipynb 1\n",
+       "# %% ../../04_export.ipynb 1\n",
        "def d(): ...\n",
        "```"
       ],
@@ -739,9 +728,9 @@
    "source": [
     "try:\n",
     "    g = exec_import('tmp.test.testing', '*')\n",
-    "    for s in \"a c d\".split(): assert s in g, s\n",
-    "    assert 'b' not in g\n",
-    "    assert g['a']() is None\n",
+    "    for s in \"b c d\".split(): assert s in g, s\n",
+    "    assert 'a' not in g\n",
+    "    assert g['b']() is None\n",
     "finally: shutil.rmtree('tmp')"
    ]
   },
diff --git a/nbs/api/04_export.ipynb b/nbs/api/04_export.ipynb

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+"""Strip superfluous metadata from notebooks"""`
	`2`	`+`
`1`	`3`	`# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/11_clean.ipynb.`
`2`	`4`
`3`	`5`	`# %% auto 0`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+"""CLI commands"""`
	`2`	`+`
`1`	`3`	`# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/13_cli.ipynb.`
`2`	`4`
`3`	`5`	`# %% ../nbs/api/13_cli.ipynb 2`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+"""Generating a documentation index from a module"""`
	`2`	`+`
`1`	`3`	`# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/05_doclinks.ipynb.`
`2`	`4`
`3`	`5`	`# %% auto 0`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+"""A YAML and formatted-markdown frontmatter processor"""`
	`2`	`+`
`1`	`3`	`# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/09_frontmatter.ipynb.`
`2`	`4`
`3`	`5`	`# %% auto 0`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+"""Fix merge conflicts in jupyter notebooks"""`
	`2`	`+`
`1`	`3`	`# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/07_merge.ipynb.`
`2`	`4`
`3`	`5`	`# %% auto 0`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+"""Utilities for migrating to nbdev"""`
	`2`	`+`
`1`	`3`	`# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/16_migrate.ipynb.`
`2`	`4`
`3`	`5`	`# %% auto 0`