fixes #473

Author: jph00

nbdev/_modidx.py

@@ -100,14 +100,14 @@
                              'nbdev.maker._filt_dec': ('09_API/maker.html#_filt_dec', 'nbdev/maker.py'),
                              'nbdev.maker._import2relative': ('09_API/maker.html#_import2relative', 'nbdev/maker.py'),
                              'nbdev.maker._mark_text_ranges': ('09_API/maker.html#_mark_text_ranges', 'nbdev/maker.py'),
+                             'nbdev.maker._retr_mdoc': ('09_API/maker.html#_retr_mdoc', 'nbdev/maker.py'),
                              'nbdev.maker._val_or_id': ('09_API/maker.html#_val_or_id', 'nbdev/maker.py'),
                              'nbdev.maker._wants': ('09_API/maker.html#_wants', 'nbdev/maker.py'),
                              'nbdev.maker.decor_id': ('09_API/maker.html#decor_id', 'nbdev/maker.py'),
                              'nbdev.maker.find_var': ('09_API/maker.html#find_var', 'nbdev/maker.py'),
                              'nbdev.maker.make_code_cells': ('09_API/maker.html#make_code_cells', 'nbdev/maker.py'),
                              'nbdev.maker.read_var': ('09_API/maker.html#read_var', 'nbdev/maker.py'),
                              'nbdev.maker.relative_import': ('09_API/maker.html#relative_import', 'nbdev/maker.py'),
-                             'nbdev.maker.retr_exports': ('09_API/maker.html#retr_exports', 'nbdev/maker.py'),
                              'nbdev.maker.update_import': ('09_API/maker.html#update_import', 'nbdev/maker.py'),
                              'nbdev.maker.update_var': ('09_API/maker.html#update_var', 'nbdev/maker.py')},
             'nbdev.merge': { 'nbdev.merge._git_branch_merge': ('09_API/merge.html#_git_branch_merge', 'nbdev/merge.py'),

nbdev/config.py

@@ -1,10 +1,17 @@
+"""Read and write nbdev's `settings.ini file.
+`get_config` is the main function for reading settings."""
+
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/09_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/09_API/01_config.ipynb 2
+_doc_ = """Read and write nbdev's `settings.ini file.
+`get_config` is the main function for reading settings."""
+
+# %% ../nbs/09_API/01_config.ipynb 3
 from datetime import datetime
 from fastcore.utils import *
 from fastcore.meta import *
@@ -17,16 +24,16 @@
 from execnb.nbio import read_nb,NbCell
 from urllib.error import HTTPError
 
-# %% ../nbs/09_API/01_config.ipynb 7
+# %% ../nbs/09_API/01_config.ipynb 8
 _nbdev_home_dir = 'nbdev' # sub-directory of xdg base dir
 _nbdev_cfg_name = 'settings.ini'
 
-# %% ../nbs/09_API/01_config.ipynb 8
+# %% ../nbs/09_API/01_config.ipynb 9
 def _git_repo():
     try: return repo_details(run('git config --get remote.origin.url'))[1]
     except OSError: return
 
-# %% ../nbs/09_API/01_config.ipynb 10
+# %% ../nbs/09_API/01_config.ipynb 11
 def _apply_defaults(
     cfg,
     lib_name='%(repo)s', # Package name
@@ -70,24 +77,23 @@ def _apply_defaults(
         cfg[k] = v
     return cfg
 
-# %% ../nbs/09_API/01_config.ipynb 11
+# %% ../nbs/09_API/01_config.ipynb 12
 def _get_info(owner, repo, default_branch='main', default_kw='nbdev'):
     from ghapi.all import GhApi
     api = GhApi(owner=owner, repo=repo, token=os.getenv('GITHUB_TOKEN'))
 
     try: r = api.repos.get()
     except HTTPError:
-        msg= [f"""Could not access repo: {owner}/{repo} to find your default branch - `{default_branch} assumed.
+        msg= [f"""Could not access repo: {owner}/{repo} to find your default branch - `{default_branch}` assumed.
 Edit `settings.ini` if this is incorrect.
 In the future, you can allow nbdev to see private repos by setting the environment variable GITHUB_TOKEN as described here:
-https://nbdev.fast.ai/cli.html#Using-nbdev_new-with-private-repos
-"""]
+https://nbdev.fast.ai/cli.html#Using-nbdev_new-with-private-repos"""]
         print(''.join(msg))
-        return (default_branch,default_kw,'')
+        return default_branch,default_kw,''
 
     return r.default_branch, default_kw if not r.topics else ' '.join(r.topics), r.description
 
-# %% ../nbs/09_API/01_config.ipynb 13
+# %% ../nbs/09_API/01_config.ipynb 14
 def _fetch_from_git(raise_err=False):
     "Get information for settings.ini from the user."
     res={}
@@ -103,7 +109,7 @@ def _fetch_from_git(raise_err=False):
     else: res['lib_name'] = res['repo'].replace('-','_')
     return res
 
-# %% ../nbs/09_API/01_config.ipynb 15
+# %% ../nbs/09_API/01_config.ipynb 16
 def _prompt_user(cfg, inferred):
     "Let user input values not in `cfg` or `inferred`."
     res = cfg.copy()
@@ -117,7 +123,7 @@ def _prompt_user(cfg, inferred):
                 print(msg+res[k]+' # Automatically inferred from git')
     return res
 
-# %% ../nbs/09_API/01_config.ipynb 17
+# %% ../nbs/09_API/01_config.ipynb 18
 def _cfg2txt(cfg, head, sections, tail=''):
     "Render `cfg` with commented sections."
     nm = cfg.d.name
@@ -129,7 +135,7 @@ def _cfg2txt(cfg, head, sections, tail=''):
     res += tail
     return res.strip()
 
-# %% ../nbs/09_API/01_config.ipynb 19
+# %% ../nbs/09_API/01_config.ipynb 20
 _nbdev_cfg_head = '''# All sections below are required unless otherwise specified.
 # See https://github.com/fastai/nbdev/blob/master/settings.ini for examples.
 
@@ -144,7 +150,7 @@ def _cfg2txt(cfg, head, sections, tail=''):
 # console_scripts =
 '''
 
-# %% ../nbs/09_API/01_config.ipynb 20
+# %% ../nbs/09_API/01_config.ipynb 21
 @call_parse
 @delegates(_apply_defaults, but='cfg')
 def nbdev_create_config(
@@ -169,19 +175,19 @@ def nbdev_create_config(
     cfg_fn = Path(path)/cfg_name
     print(f'{cfg_fn} created.')
 
-# %% ../nbs/09_API/01_config.ipynb 23
+# %% ../nbs/09_API/01_config.ipynb 24
 def _nbdev_config_file(cfg_name=_nbdev_cfg_name, path=None):
     cfg_path = path = Path.cwd() if path is None else Path(path)
     while cfg_path != cfg_path.parent and not (cfg_path/cfg_name).exists(): cfg_path = cfg_path.parent
     if not (cfg_path/cfg_name).exists(): cfg_path = path
     return cfg_path/cfg_name
 
-# %% ../nbs/09_API/01_config.ipynb 25
+# %% ../nbs/09_API/01_config.ipynb 26
 def _xdg_config_paths(cfg_name=_nbdev_cfg_name):
     xdg_config_paths = reversed([xdg_config_home()]+xdg_config_dirs())
     return [o/_nbdev_home_dir/cfg_name for o in xdg_config_paths]
 
-# %% ../nbs/09_API/01_config.ipynb 26
+# %% ../nbs/09_API/01_config.ipynb 27
 _types = dict(custom_sidebar=bool, nbs_path=Path, lib_path=Path, doc_path=Path, recursive=bool, 
     black_formatting=bool, jupyter_hooks=bool, clean_ids=bool, custom_quarto_yml=bool)
 
@@ -193,22 +199,22 @@ def get_config(cfg_name=_nbdev_cfg_name, path=None):
     cfg = Config(cfg_file.parent, cfg_file.name, extra_files=extra_files, types=_types)
     return _apply_defaults(cfg)
 
-# %% ../nbs/09_API/01_config.ipynb 41
+# %% ../nbs/09_API/01_config.ipynb 42
 def config_key(c, default=None, path=True, missing_ok=None):
     "Deprecated: use `get_config().get` or `get_config().path` instead."
     warn("`config_key` is deprecated. Use `get_config().get` or `get_config().path` instead.", DeprecationWarning)
     return get_config().path(c, default) if path else get_config().get(c, default)
 
-# %% ../nbs/09_API/01_config.ipynb 43
+# %% ../nbs/09_API/01_config.ipynb 44
 def create_output(txt, mime):
     "Add a cell output containing `txt` of the `mime` text MIME sub-type"
     return [{"data": { f"text/{mime}": str(txt).splitlines(True) },
              "execution_count": 1, "metadata": {}, "output_type": "execute_result"}]
 
-# %% ../nbs/09_API/01_config.ipynb 44
+# %% ../nbs/09_API/01_config.ipynb 45
 def show_src(src, lang='python'): return Markdown(f'```{lang}\n{src}\n```')
 
-# %% ../nbs/09_API/01_config.ipynb 47
+# %% ../nbs/09_API/01_config.ipynb 48
 _re_version = re.compile('^__version__\s*=.*$', re.MULTILINE)
 _init = '__init__.py'
 
@@ -237,13 +243,13 @@ def add_init(path=None):
         if _has_py(fs) or any(filter(_has_py, subds)) and not (r/_init).exists(): (r/_init).touch()
     update_version(path)
 
-# %% ../nbs/09_API/01_config.ipynb 50
+# %% ../nbs/09_API/01_config.ipynb 51
 def write_cells(cells, hdr, file, offset=0):
     "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(): file.write(f'\n\n{hdr} {cell.idx_+offset}\n{cell.source}')
 
-# %% ../nbs/09_API/01_config.ipynb 51
+# %% ../nbs/09_API/01_config.ipynb 52
 def _basic_export_nb(fname, name, dest=None):
     "Basic exporter to bootstrap nbdev."
     if dest is None: dest = get_config().lib_path

nbdev/maker.py

@@ -4,8 +4,7 @@
 from __future__ import annotations
 
 # %% auto 0
-__all__ = ['find_var', 'read_var', 'update_var', 'ModuleMaker', 'decor_id', 'retr_exports', 'make_code_cells', 'relative_import',
-           'update_import']
+__all__ = ['find_var', 'read_var', 'update_var', 'ModuleMaker', 'decor_id', 'make_code_cells', 'relative_import', 'update_import']
 
 # %% ../nbs/09_API/02_maker.ipynb 3
 from .config import *
@@ -88,7 +87,11 @@ def _filt_dec(x): return decor_id(x).startswith('patch')
 def _wants(o): return isinstance(o,_def_types) and not any(L(o.decorator_list).filter(_filt_dec))
 
 # %% ../nbs/09_API/02_maker.ipynb 20
-def retr_exports(trees):
+@patch
+def make_all(self:ModuleMaker, cells):
+    "Create `__all__` with all exports in `cells`"
+    if cells is None: return ''
+    trees = L(cells).map(NbCell.parsed_).concat()
     # include anything mentioned in "_all_", even if otherwise private
     # NB: "_all_" can include strings (names), or symbols, so we look for "id" or "value"
     assigns = trees.filter(risinstance(_assign_types))
@@ -101,16 +104,9 @@ def retr_exports(trees):
     return (exports+all_vals).unique()
 
 # %% ../nbs/09_API/02_maker.ipynb 21
-@patch
-def make_all(self:ModuleMaker, cells):
-    "Create `__all__` with all exports in `cells`"
-    if cells is None: return ''
-    return retr_exports(L(cells).map(NbCell.parsed_).concat())
-
-# %% ../nbs/09_API/02_maker.ipynb 22
 def make_code_cells(*ss): return dict2nb({'cells':L(ss).map(mk_cell)}).cells
 
-# %% ../nbs/09_API/02_maker.ipynb 25
+# %% ../nbs/09_API/02_maker.ipynb 24
 def relative_import(name, fname, level=0):
     "Convert a module `name` to a name relative to `fname`"
     assert not level
@@ -122,7 +118,7 @@ def relative_import(name, fname, level=0):
     if not all(o=='.' for o in res): res='.'+res
     return res.replace(os.path.sep, ".")
 
-# %% ../nbs/09_API/02_maker.ipynb 27
+# %% ../nbs/09_API/02_maker.ipynb 26
 # Based on https://github.com/thonny/thonny/blob/master/thonny/ast_utils.py
 def _mark_text_ranges(
     source: str|bytes, # Source code to add ranges to
@@ -140,7 +136,7 @@ def _mark_text_ranges(
             child.end_lineno, child.end_col_offset = child.lineno, child.col_offset+2
     return root.body
 
-# %% ../nbs/09_API/02_maker.ipynb 28
+# %% ../nbs/09_API/02_maker.ipynb 27
 def update_import(source, tree, libname, f=relative_import):
     if not tree: return
     if sys.version_info < (3,8): tree = _mark_text_ranges(source)
@@ -160,7 +156,7 @@ def import2relative(cell:NbCell, libname):
     src = update_import(cell.source, cell.parsed_(), libname)
     if src: cell.set_source(src)
 
-# %% ../nbs/09_API/02_maker.ipynb 30
+# %% ../nbs/09_API/02_maker.ipynb 29
 @patch
 def _last_future(self:ModuleMaker, cells):
     "Returns the location of a `__future__` in `cells`"
@@ -169,13 +165,21 @@ def _last_future(self:ModuleMaker, cells):
          isinstance(t,ast.ImportFrom) and t.module=='__future__' for t in tree))+1
     except ValueError: return 0
 
-# %% ../nbs/09_API/02_maker.ipynb 31
+# %% ../nbs/09_API/02_maker.ipynb 30
 def _import2relative(cells, lib_name=None):
     "Converts `cells` to use `import2relative` based on `lib_name`"
     if lib_name is None: lib_name = get_config().lib_name
     for cell in cells: cell.import2relative(lib_name)
 
-# %% ../nbs/09_API/02_maker.ipynb 32
+# %% ../nbs/09_API/02_maker.ipynb 31
+def _retr_mdoc(cells):
+    "Search for `_doc_` variable, used to create module docstring"
+    trees = L(cells).map(NbCell.parsed_).concat()
+    res = [nested_attr(o, 'value.value') for o in trees
+           if isinstance(o, _assign_types) and getattr(o.targets[0],'id',None)=='_doc_']
+    return res[0] if res else None
+
+# %% ../nbs/09_API/02_maker.ipynb 33
 @patch
 def make(self:ModuleMaker, cells, all_cells=None, lib_path=None):
     "Write module containing `cells` with `__all__` generated from `all_cells`"
@@ -195,24 +199,27 @@ def make(self:ModuleMaker, cells, all_cells=None, lib_path=None):
         tw = TextWrapper(width=120, initial_indent='', subsequent_indent=' '*11, break_long_words=False)
         all_str = '\n'.join(tw.wrap(str(_all)))
     with self.fname.open('w') as f:
+        mdoc = _retr_mdoc(cells)
+        if mdoc: f.write(f'"""{mdoc}"""\n\n')
         f.write(f"# AUTOGENERATED! DO NOT EDIT! File to edit: {self.dest2nb}.")
         if last_future > 0: write_cells(cells[:last_future], self.hdr, f)
         if self.parse: f.write(f"\n\n# %% auto 0\n__all__ = {all_str}")
         write_cells(cells[last_future:], self.hdr, f)
         f.write('\n')
 
-# %% ../nbs/09_API/02_maker.ipynb 37
+# %% ../nbs/09_API/02_maker.ipynb 38
 @patch
 def _update_all(self:ModuleMaker, all_cells, alls):
     return pformat(alls + self.make_all(all_cells), width=160)
 
 @patch
 def _make_exists(self:ModuleMaker, cells, all_cells=None):
     "`make` for `is_new=False`"
-    if all_cells and self.parse: update_var('__all__', partial(self._update_all, all_cells), fn=self.fname)
+    if all_cells and self.parse:
+        update_var('__all__', partial(self._update_all, all_cells), fn=self.fname)
     with self.fname.open('a') as f: write_cells(cells, self.hdr, f)
 
-# %% ../nbs/09_API/02_maker.ipynb 43
+# %% ../nbs/09_API/02_maker.ipynb 44
 def _basic_export_nb2(fname, name, dest=None):
     "A basic exporter to bootstrap nbdev using `ModuleMaker`"
     if dest is None: dest = get_config().lib_path

nbs/09_API/01_config.ipynb

@@ -19,6 +19,17 @@
     "#|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,
@@ -174,13 +185,12 @@
     "    \n",
     "    try: r = api.repos.get()\n",
     "    except HTTPError:\n",
-    "        msg= [f\"\"\"Could not access repo: {owner}/{repo} to find your default branch - `{default_branch} assumed.\n",
+    "        msg= [f\"\"\"Could not access repo: {owner}/{repo} to find your default branch - `{default_branch}` assumed.\n",
     "Edit `settings.ini` if this is incorrect.\n",
     "In the future, you can allow nbdev to see private repos by setting the environment variable GITHUB_TOKEN as described here:\n",
-    "https://nbdev.fast.ai/cli.html#Using-nbdev_new-with-private-repos\n",
-    "\"\"\"]\n",
+    "https://nbdev.fast.ai/cli.html#Using-nbdev_new-with-private-repos\"\"\"]\n",
     "        print(''.join(msg))\n",
-    "        return (default_branch,default_kw,'')\n",
+    "        return default_branch,default_kw,''\n",
     "    \n",
     "    return r.default_branch, default_kw if not r.topics else ' '.join(r.topics), r.description"
    ]
@@ -189,16 +199,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "/Users/jhoward/git/ghapi/ghapi/core.py:99: UserWarning: Neither GITHUB_TOKEN nor GITHUB_JWT_TOKEN found: running as unauthenticated\n",
-      "  else: warn('Neither GITHUB_TOKEN nor GITHUB_JWT_TOKEN found: running as unauthenticated')\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "#|hide\n",
     "if os.getenv('GITHUB_ACTIONS') != 'true': # GITHUB_TOKEN in actions has limited scope.\n",