nbdev 3.3.0__tar.gz → 3.3.2__tar.gz

{nbdev-3.3.0/nbdev.egg-info → nbdev-3.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.0
+Version: 3.3.2
 Summary: Create delightful software with Jupyter Notebooks
 Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
 License: Apache-2.0
@@ -16,7 +16,7 @@ Classifier: License :: OSI Approved :: Apache Software License
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastcore>=2.1.3
+Requires-Dist: fastcore>=2.1.11
 Requires-Dist: execnb>=0.2.8
 Requires-Dist: astunparse
 Requires-Dist: ghapi>=2.0.2

nbdev-3.3.2/nbdev/__init__.py

@@ -0,0 +1,12 @@
+"""Create delightful software with Jupyter Notebooks
+
+Modules:
+
+- `nbdev.extract_attachments`: A preprocessor that extracts all of the attachments from the notebook file. The extracted attachments are returned in the 'resources' dictionary.
+- `nbdev.skill`: Author clear, executable nbdev notebooks where code, prose, examples, outputs, and tests form one coherent narrative."""
+
+__version__ = "3.3.2"
+
+from .doclinks import nbdev_export
+from .showdoc import show_doc
+

{nbdev-3.3.0 → nbdev-3.3.2}/nbdev/_modidx.py

@@ -52,7 +52,13 @@ d = { 'settings': { 'branch': 'main',
                               'nbdev.config._git_repo': ('api/config.html#_git_repo', 'nbdev/config.py'),
                               'nbdev.config._has_nbdev': ('api/config.html#_has_nbdev', 'nbdev/config.py'),
                               'nbdev.config._has_py': ('api/config.html#_has_py', 'nbdev/config.py'),
+                              'nbdev.config._index_mdoc': ('api/config.html#_index_mdoc', 'nbdev/config.py'),
                               'nbdev.config._load_toml': ('api/config.html#_load_toml', 'nbdev/config.py'),
+                              'nbdev.config._mod_docstr': ('api/config.html#_mod_docstr', 'nbdev/config.py'),
+                              'nbdev.config._modline': ('api/config.html#_modline', 'nbdev/config.py'),
+                              'nbdev.config._pkg_docparts': ('api/config.html#_pkg_docparts', 'nbdev/config.py'),
+                              'nbdev.config._pkg_mods': ('api/config.html#_pkg_mods', 'nbdev/config.py'),
+                              'nbdev.config._substantive': ('api/config.html#_substantive', 'nbdev/config.py'),
                               'nbdev.config._user_config': ('api/config.html#_user_config', 'nbdev/config.py'),
                               'nbdev.config.add_init': ('api/config.html#add_init', 'nbdev/config.py'),
                               'nbdev.config.bump_version': ('api/config.html#bump_version', 'nbdev/config.py'),
@@ -63,9 +69,13 @@ d = { 'settings': { 'branch': 'main',
                               'nbdev.config.nbdev_create_config': ('api/config.html#nbdev_create_config', 'nbdev/config.py'),
                               'nbdev.config.nbpath2docurl': ('api/config.html#nbpath2docurl', 'nbdev/config.py'),
                               'nbdev.config.nbpath2html': ('api/config.html#nbpath2html', 'nbdev/config.py'),
+                              'nbdev.config.pkg_llms': ('api/config.html#pkg_llms', 'nbdev/config.py'),
+                              'nbdev.config.pkg_mdoc': ('api/config.html#pkg_mdoc', 'nbdev/config.py'),
                               'nbdev.config.read_version': ('api/config.html#read_version', 'nbdev/config.py'),
                               'nbdev.config.set_version': ('api/config.html#set_version', 'nbdev/config.py'),
                               'nbdev.config.show_src': ('api/config.html#show_src', 'nbdev/config.py'),
+                              'nbdev.config.update_init_mdoc': ('api/config.html#update_init_mdoc', 'nbdev/config.py'),
+                              'nbdev.config.update_llms_txt': ('api/config.html#update_llms_txt', 'nbdev/config.py'),
                               'nbdev.config.update_proj': ('api/config.html#update_proj', 'nbdev/config.py'),
                               'nbdev.config.update_version': ('api/config.html#update_version', 'nbdev/config.py'),
                               'nbdev.config.write_cells': ('api/config.html#write_cells', 'nbdev/config.py')},
@@ -118,7 +128,8 @@ d = { 'settings': { 'branch': 'main',
                               'nbdev.export.ExportModuleProc._export_': ('api/export.html#exportmoduleproc._export_', 'nbdev/export.py'),
                               'nbdev.export.ExportModuleProc._exporti_': ('api/export.html#exportmoduleproc._exporti_', 'nbdev/export.py'),
                               'nbdev.export.ExportModuleProc.begin': ('api/export.html#exportmoduleproc.begin', 'nbdev/export.py'),
-                              'nbdev.export.nb_export': ('api/export.html#nb_export', 'nbdev/export.py')},
+                              'nbdev.export.nb_export': ('api/export.html#nb_export', 'nbdev/export.py'),
+                              'nbdev.export.nb_mdoc': ('api/export.html#nb_mdoc', 'nbdev/export.py')},
             'nbdev.extract_attachments': {},
             'nbdev.frontmatter': { 'nbdev.frontmatter.FrontmatterProc': ('api/frontmatter.html#frontmatterproc', 'nbdev/frontmatter.py'),
                                    'nbdev.frontmatter.FrontmatterProc._update': ( 'api/frontmatter.html#frontmatterproc._update',

{nbdev-3.3.0 → nbdev-3.3.2}/nbdev/clean.py

@@ -149,7 +149,7 @@ def _to_meta(cell, names):
 
 def _to_comments(cell, names):
     "Move directives in `names` from the cell's `nbdev` metadata key to comments"
-    move = {k:v for k,v in _meta_directives(cell).items() if k in names}
+    move = {k:v for k,v in _meta_directives(cell.get('metadata')).items() if k in names}
     if not move: return
     nbd = cell.metadata['nbdev']
     for k in move: nbd.pop(k, None)

{nbdev-3.3.0 → nbdev-3.3.2}/nbdev/cli.py

@@ -11,6 +11,7 @@ __all__ = ['mapping', 'nbdev_filter', 'extract_tgz', 'nbdev_new', 'nbdev_update_
 # %% ../nbs/api/13_cli.ipynb #6a35c7c4-748f-4c82-a9bf-c780a8d83e90
 import warnings
 import time
+from typing import Annotated
 
 from .config import *
 from .process import *
@@ -72,7 +73,7 @@ def _render_nb(fn, cfg):
 
 # %% ../nbs/api/13_cli.ipynb #dd385911-aa8f-44e7-8d46-7b8a20f3b010
 async def _update_repo_meta(cfg):
-    "Enable gh pages and update the homepage and description in your GitHub repo."
+    "Update the homepage and description in your GitHub repo."
     token=os.getenv('GITHUB_TOKEN')
     if token:
         from ghapi.core import GhApi, APIError
@@ -82,24 +83,28 @@ async def _update_repo_meta(cfg):
                   "Use a token with the correction permissions or perform these steps manually.")
 
 # %% ../nbs/api/13_cli.ipynb #c4a663d9
+_pos = Annotated[str, {'opt':False, 'nargs':'?'}]  # optional positional CLI arg
+
 @call_parse
 @delegates(nbdev_create_config)
-async def nbdev_new(**kwargs):
+async def nbdev_new(
+    name:_pos=None, # Directory to create and scaffold in (defaults to the current directory)
+    template:str='answerdotai/nbdev3-template', # Template repo
+    tag:str=None, # Template release tag (defaults to the latest release)
+    **kwargs):
     "Create an nbdev project."
     from ghapi.core import GhApi
+    if name:
+        Path(name).mkdir(exist_ok=True)
+        os.chdir(name)
+        kwargs.setdefault('repo', name)
     nbdev_create_config.__wrapped__(**kwargs)
     cfg = get_config()
     if (Path('.git')).exists(): await _update_repo_meta(cfg)
     else: print(f"No git repo found. Run: gh repo create {cfg.user}/{cfg.repo} --public --source=.")
     path = Path()
 
-    _ORG_OR_USR,_REPOSITORY = 'answerdotai','nbdev3-template'
-    _TEMPLATE = f'{_ORG_OR_USR}/{_REPOSITORY}'
-    template = kwargs.get('template', _TEMPLATE)
-    try: org_or_usr, repo = template.split('/')
-    except ValueError: org_or_usr, repo = _ORG_OR_USR, _REPOSITORY
-
-    tag = kwargs.get('tag', None)
+    org_or_usr,repo = template.split('/')
     if tag is None:
         with warnings.catch_warnings():
             warnings.simplefilter('ignore', UserWarning)

{nbdev-3.3.0 → nbdev-3.3.2}/nbdev/config.py

@@ -7,7 +7,8 @@ Docs: https://nbdev.fast.ai/api/config.html.md"""
 # %% auto #0
 __all__ = ['pyproject_nm', 'pyproject_tmpl', 'nbdev_defaults', 'pyproj_tmpl', 'nbdev_create_config', 'ConfigToml', 'get_config',
            'is_nbdev', 'create_output', 'show_src', 'nbpath2html', 'nbpath2docurl', 'read_version', 'set_version',
-           'bump_version', 'update_version', 'update_proj', 'add_init', 'import_obj', 'write_cells']
+           'bump_version', 'update_version', 'update_proj', 'add_init', 'pkg_mdoc', 'update_init_mdoc', 'pkg_llms',
+           'update_llms_txt', 'import_obj', 'write_cells']
 
 # %% ../nbs/api/01_config.ipynb #6fd14ecd
 from datetime import datetime
@@ -54,16 +55,19 @@ https://nbdev.fast.ai/api/release.html#setup"""]
 def _fetch_from_git(raise_err=False):
     "Get information for pyproject.toml from git."
     res={}
+    try:
+        res['author'] = run('git config --get user.name').strip()
+        res['author_email'] = run('git config --get user.email').strip()
+    except OSError as e:
+        if raise_err: raise e
     try:
         url = run('git config --get remote.origin.url')
         res['user'],res['repo'] = repo_details(url)
         res['branch'],res['keywords'],desc = _get_info(owner=res['user'], repo=res['repo'])
         if desc: res['description'] = desc
-        res['author'] = run('git config --get user.name').strip()
-        res['author_email'] = run('git config --get user.email').strip()
+        res['lib_name'] = res['repo'].replace('-','_')
     except OSError as e:
-        if raise_err: raise(e)
-    else: res['lib_name'] = res['repo'].replace('-','_')
+        if raise_err: raise e
     return res
 
 # %% ../nbs/api/01_config.ipynb #05aae09f
@@ -352,6 +356,104 @@ def add_init(path=None):
         if _has_py(fs) or any(filter(_has_py, subds)) and not (r/_init).exists(): (r/_init).touch()
     if get_config().get('put_version_in_init', True): update_version(path)
     if get_config().get('update_pyproject', True): update_proj(path.parent)
+    update_init_mdoc(path)
+
+# %% ../nbs/api/01_config.ipynb #a01b98bb
+def _mod_docstr(py_path):
+    "Module docstring of `py_path` via ast, without importing ('' if none or unparseable)"
+    try: return ast.get_docstring(ast.parse(Path(py_path).read_text(encoding='utf-8'))) or ''
+    except SyntaxError: return ''
+
+def _substantive(docstr):
+    "Does `docstr` say more than the default summary line plus `Docs:` link?"
+    return len(docstr.strip().splitlines())>3
+
+def _pkg_mods(path):
+    "`(name, summary, url)` per module of `path` with a substantive docstring: dotted name, one-line first para, `Docs:` url"
+    res = []
+    for p in sorted(Path(path).rglob('*.py')):
+        if p.name.startswith('_'): continue
+        d = _mod_docstr(p)
+        if not _substantive(d): continue
+        nm = '.'.join((Path(path).name, *p.relative_to(path).with_suffix('').parts))
+        summ = ' '.join(d.split('\n\n')[0].splitlines())
+        last = d.strip().splitlines()[-1]
+        res.append((nm, summ, last[5:].strip() if last.startswith('Docs:') else ''))
+    return res
+
+def _index_mdoc(idx_path):
+    "Package docstring intro: bodies of md cells with an export directive, and fenced `exportd` cells, from the index nb"
+    if not idx_path or not Path(idx_path).exists(): return ''
+    docs = []
+    for c in read_nb(idx_path).cells:
+        lines = c.source.splitlines()
+        n = 0
+        while n<len(lines) and lines[n].startswith('#|'): n += 1
+        dirs = {l[2:].strip().split()[0] for l in lines[:n] if l[2:].strip()}
+        body = '\n'.join(lines[n:]).strip()
+        if not body or not {'export','exportd'}&dirs: continue
+        docs.append(body if c.cell_type=='markdown' else fenced(body, 'python'))
+    return '\n\n'.join(docs)
+
+def _pkg_docparts(path=None, desc=None, index_nb=None):
+    "`(path, desc, intro, mods)` shared by `pkg_mdoc` and `pkg_llms`"
+    path = Path(path or get_config().lib_path)
+    mods = _pkg_mods(path)
+    if index_nb is None:
+        cfg = get_config()
+        if path==Path(cfg.lib_path): index_nb = cfg.nbs_path/cfg.readme_nb
+    intro = _index_mdoc(index_nb)
+    if (mods or intro) and desc is None: desc = get_config().description
+    return path,desc,intro,mods
+
+def pkg_mdoc(path=None, desc=None, index_nb=None):
+    "Package docstring for `path`: `desc`, intro from `index_nb`, and a line per module with a substantive docstring"
+    path,desc,intro,mods = _pkg_docparts(path, desc, index_nb)
+    if not mods and not intro: return ''
+    mods = ['Modules:', '\n'.join(f'- `{nm}`: {summ}' for nm,summ,url in mods)] if mods else []
+    return '\n\n'.join(filter(None, [desc, intro, *mods]))
+
+# %% ../nbs/api/01_config.ipynb #a03a0007
+def update_init_mdoc(path=None, desc=None):
+    "Write `pkg_mdoc` as the docstring of `path/__init__.py`, replacing any existing docstring"
+    path = Path(path or get_config().lib_path)
+    mdoc = pkg_mdoc(path, desc=desc)
+    if not mdoc: return
+    fn = path/'__init__.py'
+    txt = fn.read_text(encoding='utf-8') if fn.exists() else ''
+    body = ast.parse(txt).body
+    rest = txt
+    if body and isinstance(body[0], ast.Expr) and isinstance(getattr(body[0].value, 'value', None), str):
+        rest = ''.join(txt.splitlines(keepends=True)[body[0].end_lineno:])
+    res = f'"""{mdoc}"""\n'
+    if rest.strip(): res += '\n'+rest.lstrip('\n')
+    fn.write_text(res, encoding='utf-8')
+
+# %% ../nbs/api/01_config.ipynb #f9912ef7
+_llms_marker = '<!-- Generated by nbdev-export; edit the index notebook, not this file -->'
+
+def _modline(nm, summ, url):
+    "llms.txt list line: linked when `url` is a single URL, else the `Docs:` text carried verbatim"
+    if url and ' ' not in url: return f'- [{nm}]({url}): {summ}'
+    return f'- `{nm}`: {summ} (Docs: {url})' if url else f'- `{nm}`: {summ}'
+
+def pkg_llms(path=None, desc=None, index_nb=None):
+    "llms.txt for the package at `path`, from the same sources as `pkg_mdoc` ('' if no intro or modules)"
+    path,desc,intro,mods = _pkg_docparts(path, desc, index_nb)
+    if not mods and not intro: return ''
+    if mods:
+        links = '\n'.join(_modline(*o) for o in mods)
+        mods = [f'## Modules\n\n{links}']
+    parts = [f'# {path.name}', f'> {desc}' if desc else '', intro, *mods, _llms_marker]
+    return '\n\n'.join(filter(None, parts)) + '\n'
+
+def update_llms_txt(path=None, fn=None, desc=None, index_nb=None):
+    "Write `pkg_llms` to `fn` when it's absent or generated (has the nbdev marker); never touch a hand-written file"
+    if fn is None: fn = get_config().nbs_path/'llms.txt'
+    txt = pkg_llms(path, desc=desc, index_nb=index_nb)
+    if not txt: return
+    if fn.exists() and _llms_marker not in fn.read_text(encoding='utf-8'): return
+    fn.write_text(txt, encoding='utf-8')
 
 # %% ../nbs/api/01_config.ipynb #95cebda6
 def import_obj(s):
@@ -364,7 +466,7 @@ def import_obj(s):
 def write_cells(cells, hdr, file, solo_nb=False):
     "Write `cells` to `file` along with header `hdr` (mainly for nbdev internal use)."
     for cell in cells:
-        if cell.cell_type=='code' and cell.source.strip():
+        if cell.cell_type=='code' and cell.source.strip() and 'exportd' not in getattr(cell,'directives_',{}):
             cell_id = f" #{cell.id}" if cell.get('id') else ""
             file.write(f'\n\n{hdr}{cell_id}\n{cell.source}') if not solo_nb else file.write(f'\n\n{cell.source}')
 

{nbdev-3.3.0 → nbdev-3.3.2}/nbdev/doclinks.py

@@ -155,6 +155,7 @@ def nbdev_export(
         files = nbglob(path=path, as_path=True, **kwargs).sorted('name')
         for f in files: nb_export(f, procs=procs)
         add_init(cfg.lib_path)
+        update_llms_txt()
         _build_modidx()
 
 # %% ../nbs/api/05_doclinks.ipynb #3134c22b

{nbdev-3.3.0 → nbdev-3.3.2}/nbdev/export.py

@@ -5,11 +5,12 @@ Docs: https://nbdev.fast.ai/api/export.html.md"""
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/04_export.ipynb.
 
 # %% auto #0
-__all__ = ['ExportModuleProc', 'nb_export']
+__all__ = ['ExportModuleProc', 'nb_export', 'nb_mdoc']
 
 # %% ../nbs/api/04_export.ipynb #3b932371
 from .config import *
 from .maker import *
+from .maker import _retr_mdoc
 from .imports import *
 from .process import *
 
@@ -32,8 +33,8 @@ class ExportModuleProc:
     def __call__(self, cell):
         src = cell.source
         if not src: return
-        if cell.cell_type=='markdown' and (src.startswith('# ') or 'export' in cell.directives_): self._exporti_(cell)
-    _exports_=_export_
+        if cell.cell_type=='markdown' and (src.startswith('# ') or {'export','exportd'}&set(cell.directives_)): self._exporti_(cell)
+    _exports_,_exportd_=_export_,_exporti_
 
 # %% ../nbs/api/04_export.ipynb #76717e36
 def nb_export(
@@ -51,7 +52,7 @@ def nb_export(
     nb = NBProcessor(nbname, [exp]+L(procs), debug=debug)
     nb.process()
     for mod,cells in exp.modules.items():
-        if first(1 for o in cells if o.cell_type=='code'):
+        if first(1 for o in cells if o.cell_type=='code' and 'exportd' not in o.directives_):
             all_cells = exp.in_all[mod]
             nm = ifnone(name, getattr(exp, 'default_exp', None) if mod=='#' else mod)
             if not nm:
@@ -61,3 +62,10 @@ def nb_export(
                 return
             mm = mod_maker(dest=lib_path, name=nm, nb_path=nbname, is_new=bool(name) or mod=='#', solo_nb=solo_nb)
             mm.make(cells, all_cells, lib_path=lib_path)
+
+# %% ../nbs/api/04_export.ipynb #f7ce4b21
+def nb_mdoc(nbname:str): # Filename of notebook
+    "The module docstring `nb_export` would write for `nbname`, for previewing while authoring"
+    exp = ExportModuleProc()
+    NBProcessor(nbname, exp).process()
+    return PrettyString(_retr_mdoc(exp.modules['#'], nbname))

{nbdev-3.3.0 → nbdev-3.3.2}/nbdev/maker.py

@@ -177,13 +177,17 @@ def _import2relative(cells, lib_path=None):
 
 # %% ../nbs/api/02_maker.ipynb #5bff9d71
 def _retr_mdoc(cells, nb_path=None):
-    "Search for markdown cells used to create module docstring"
+    "Module docstring from md cells with an export directive, plus `exportd` cells (code fenced)"
+    def _doc(o):
+        d = getattr(o,'directives_',{})
+        if o.cell_type=='markdown' and {'export','exportd'}&set(d): return o.source.rstrip()
+        if o.cell_type=='code' and 'exportd' in d: return fenced(o.source.rstrip(), 'python')
     md1 = first(o for o in cells if o.cell_type=='markdown' and o.source.startswith('# '))
     if not md1: return ''
     lines = dropwhile(lambda l: not l.startswith('> '), md1.source.splitlines())
     lines = list(takewhile(lambda l: l.startswith('> '), lines))
     summ = '\n'.join(l.lstrip('> ').strip() for l in lines)
-    docs = L(o.source.rstrip() for o in cells if o.cell_type=='markdown' and 'export' in getattr(o,'directives_',{}))
+    docs = L(cells).map(_doc).filter()
     mdoc = '\n\n'.join(L(summ)+docs).strip()
     url = nbpath2docurl(nb_path) if nb_path else ''
     if url: mdoc = (mdoc + f'\n\nDocs: {url}').strip()

{nbdev-3.3.0 → nbdev-3.3.2}/nbdev/process.py

@@ -41,7 +41,7 @@ class NBProcessor:
         self.nb = read_nb(path) if nb is None else nb
         self.lang = nb_lang(self.nb)
         for cell in self.nb.cells: cell.directives_ = cell.directives
-        nbdirs = {k:v for k,v in _meta_directives(self.nb).items() if not any(k in c.directives_ for c in self.nb.cells)}
+        nbdirs = {k:v for k,v in _meta_directives(self.nb.get('metadata')).items() if not any(k in c.directives_ for c in self.nb.cells)}
         if nbdirs:
             fc = first(c for c in self.nb.cells if c.cell_type=='code')
             if fc is not None: fc.directives_ = nbdirs | fc.directives_

{nbdev-3.3.0 → nbdev-3.3.2}/nbdev/release.py

@@ -63,7 +63,7 @@ def _release_head():
 def update_changelog(txt, ver, notes, marker='<!-- do not remove -->\n'):
     "Insert `notes` into changelog `txt` after `marker`, replacing any existing section for `ver`"
     txt = re.sub(rf'\n## {re.escape(ver)}\n.*?(?=\n## |\Z)', '', txt, flags=re.S)
-    return txt.replace(marker, marker+notes+'\n')
+    return txt.replace(marker, marker+notes.rstrip('\n')+'\n\n').rstrip('\n')+'\n'
 
 # %% ../nbs/api/18_release.ipynb #0b36471a
 class Release:

nbdev-3.3.2/nbdev/skill.py

@@ -0,0 +1,70 @@
+"""Author clear, executable nbdev notebooks where code, prose, examples, outputs, and tests form one coherent narrative.
+
+# The notebook is the product
+
+An nbdev notebook is source, docs, examples, and tests at once. The rendered page explains the public API, and executing the same cells builds and verifies it. Write it to be read top to bottom, interleaving implementation with explanation, examples, outputs, and failure demonstrations. These conventions matter most for published libraries with docs sites. In internal projects, match the surrounding notebooks instead.
+
+# Notebooks generate modules
+
+`nbdev-export` writes exported cells to the module named by `#| default_exp`. Never hand-edit generated `.py` files, `__all__`, `_modidx.py`, or generated module docstrings. The next export overwrites them. Each exported section's marker (`# %% ../nbs/04_usage.ipynb #a45f753a`) leads back to the cell to change. The module docstring is the title cell's `>` description joined with every exported markdown cell after the H1. For a long docstring, prefer one exported markdown cell per section.
+
+Projects mix notebook-sourced and plain modules: notebooks where the narrative is worth having (public API with a docs page, code best explained through examples, tests that double as documentation), plain `.py` for dense mechanism iterated quickly under `pytest`. Check the file, never the repo. A generated module opens with the `# AUTOGENERATED! DO NOT EDIT!` warning naming its source notebook, and `# %%` cell markers precede each definition, so a few lines of context around any `def` also answer it. No marker means hand-written and edited directly. Tests follow the source form: cells for notebook modules, `tests/*.py` for plain ones.
+
+For project-level questions, read `nbs/index.ipynb`, not `README.md`. The README is generated from it, renders worse, and can be stale if regeneration lagged. When they disagree, `index.ipynb` is the truth. Regenerate with `nbdev-readme` after editing it.
+
+# Structure
+
+Pick one documentation form rather than mixing accidentally: tutorial (guided learning), how-to (a practical task), explanation (a focused topic), or reference (a component and its API, easy to scan).
+
+Open with an H1 title cell plus `>` subtitle line, introduce the page in a sentence or two, and get to the subject quickly. H2 headings divide major concepts. Don't fragment a short narrative into tiny sections. Every heading goes in its own markdown cell, separate from body prose, since Jupyter collapses sections by cell.
+
+# Develop one idea at a time
+
+Add the smallest useful implementation, explain what it does and why it has that form, demonstrate it executably, assert where that improves the example, display the result a reader should notice, move on. A cell may bundle several closely related checks, but needs a markdown introduction saying what it establishes. If the introduction gets complicated, split the cell. Prefer extending an existing example over adding a near-duplicate cell. Build classes incrementally with `@patch` so each method sits beside its explanation, unless splitting makes the API harder to understand.
+
+# Helpers
+
+Internal use is often the first evidence an abstraction is worth exposing, not a reason to hide it. Reserve underscores for machinery with no coherent independent contract. A helper only useful to the library itself hints at an awkward internal design.
+
+# Prose and docstrings
+
+Markdown explains what the code cannot: why an abstraction exists, what distinction the next example demonstrates, which details are guarantees and which merely describe an example. Never narrate code line by line or write empty transitions ("Now we test the function"). State the lesson instead ("A missing leaf returns `None`, so success status alone does not establish existence"). Place prose where it reads correctly on the generated page, normally right after the definition it explains.
+
+Keep docstrings to a short statement of what the symbol does. Extended explanation, examples, and warnings go in markdown cells, where they render properly and can include executable results. Document parameters and returns with docments, keeping their docs beside the signature instead of repeating it in the docstring. Backtick symbol names in prose. nbdev links them, so prefer names over hand-maintained URLs.
+
+# Examples are documentation and tests
+
+Write each example as page content first, then make it verify behavior: realistic values, the shortest path to the idea, an informative displayed result, direct assertions that reinforce the lesson, reuse of objects introduced earlier, and important errors demonstrated executably with `expect_fail` (one focused example per contract). Keep test plumbing out of reader-facing cells. Mocks, dense comprehensions, and long setup make poor documentation, so extract a tiny helper or hide the check. Assertions verify, but only the final expression's display teaches. End cells with the value worth showing, and design a compact `_repr_markdown_` or structured summary when it turns later examples into documentation for free. Plots, tables, images, and rich HTML all count as evidence. Stored outputs are part of the explanation. Keep them focused, and never dump a large structure without saying what matters in it. Test helpers come from `fastcore.test` (`test_eq`, `expect_fail`, ...), in plain code cells.
+
+# Tells
+
+Some patterns in a test or example cell can be spotted mechanically, and each reliably signals a rewrite that would improve the page. Each is a strong hint rather than a law. In particular, a comment sometimes states a constraint the code cannot show, and such a comment stays.
+
+- A comment in an example cell usually marks where the cell should split in two. Split there, and grow the comment into a markdown cell introducing what the next code cell shows.
+- Comments numbering steps mark a tutorial sequence. Give each step its own markdown and code pair.
+- A `print` whose f-string wraps a result in a sentence is prose in code. The sentence belongs in markdown, and the value belongs at the end of the cell as its displayed result.
+- A `print(x)` as a cell's last line hides the rich repr. End with bare `x` instead.
+- A test or example cell that doesn't end in an evaluation to display (its last line is an assertion or an assignment) verifies without teaching. End with the value the checks are about.
+- One name reassigned through stages in a single cell hides the intermediate values, which are the point. Give each stage its own cell, ending with a display.
+- Blank lines dividing a cell into groups mark candidate cell boundaries, and each group needs its own sentence of markdown.
+- Adjacent near-duplicate cells differing in one argument are a comparison written as copies. Make the difference the narrative ("with `strict=True` the same call raises...").
+- `try`/`except` written to demonstrate an error is what `expect_fail` is for.
+- A triple-quoted docstring holds explanation that belongs in markdown cells. Keep the docstring to a single short line (see "Prose and docstrings").
+- `# TODO` or `# FIXME` in an example belongs nowhere on a docs page. It is an issue, or it is fixed.
+
+# State flows downward
+
+Keep imports in dedicated import cells, define values near first use, reuse established objects, don't reassign names later cells depend on, introduce shared setup explicitly, and end exploratory cells with the expression whose output records what was learned, so a reader never searches far upward for where a value came from. The import rule is strict and covers test cells. The docs build runs each import-containing cell in a fresh namespace where no other cell has run, so a cell mixing imports with other code breaks the build or silently runs at documentation time.
+
+# Directives
+
+`#| default_exp` names the module. `#| export` marks exported cells. Underscore-prefixed helpers may export without joining the public API. `#| hide` keeps necessary but distracting material off the page. `#| eval: false` is for cells that genuinely must not run, not for suppressing broken ones, and it cascades. An unevaluated cell cannot create state for later evaluated cells.
+
+# nbdev v3
+
+Everything here describes nbdev v3 (released Jan 2026, possibly after a model's training cutoff). Key user-visible changes from v2: config moved from `settings.ini` to `pyproject.toml`, with standard metadata in `[project]`, nbdev-specific keys in `[tool.nbdev]` (defaults `nbs_path='nbs'`, `doc_path='_docs'`), version in `__init__.py` via `dynamic = ["version"]`, and `_modidx` registered under `[project.entry-points.nbdev]`. CLI commands use hyphens (`nbdev-export`, `nbdev-test`, ...) though Python functions keep underscores. GitHub workflows use the v3 actions (`fastai/workflows/nbdev3-ci`, `quarto-ghp3`).
+
+# Before you finish
+
+Each new test cell ran red then green, failing before the change and passing after. Re-read the touched section as a reader would, against the conventions above. Style damage breaks no test and no export, so the harm only shows on the docs page.
+"""

{nbdev-3.3.0 → nbdev-3.3.2/nbdev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.0
+Version: 3.3.2
 Summary: Create delightful software with Jupyter Notebooks
 Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
 License: Apache-2.0
@@ -16,7 +16,7 @@ Classifier: License :: OSI Approved :: Apache Software License
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastcore>=2.1.3
+Requires-Dist: fastcore>=2.1.11
 Requires-Dist: execnb>=0.2.8
 Requires-Dist: astunparse
 Requires-Dist: ghapi>=2.0.2

{nbdev-3.3.0 → nbdev-3.3.2}/nbdev.egg-info/requires.txt

@@ -1,4 +1,4 @@
-fastcore>=2.1.3
+fastcore>=2.1.11
 execnb>=0.2.8
 astunparse
 ghapi>=2.0.2

{nbdev-3.3.0 → nbdev-3.3.2}/pyproject.toml

@@ -19,7 +19,7 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
 ]
 dynamic = ["version"]
-dependencies = [ "fastcore>=2.1.3", "execnb>=0.2.8", "astunparse", "ghapi>=2.0.2", "watchdog", "asttokens",
+dependencies = [ "fastcore>=2.1.11", "execnb>=0.2.8", "astunparse", "ghapi>=2.0.2", "watchdog", "asttokens",
     "setuptools", "build", "fastgit>=0.0.7", "pyyaml", "tomli; python_version < '3.11'", ]
 
 [project.optional-dependencies]

nbdev-3.3.0/nbdev/__init__.py

@@ -1,5 +0,0 @@
-__version__ = "3.3.0"
-
-from .doclinks import nbdev_export
-from .showdoc import show_doc
-

nbdev-3.3.0/nbdev/skill.py

@@ -1,181 +0,0 @@
-"""Author clear, executable nbdev notebooks where code, prose, examples, outputs, and tests form one coherent narrative.
-
-# The notebook is the product
-
-An nbdev notebook is simultaneously source code, documentation, examples, and tests. Write it to be read from top to bottom. The rendered page should explain the public API, while executing the same cells should build and verify it.
-
-Do not treat an nbdev notebook as a Python module divided arbitrarily into cells. Use the notebook medium deliberately: interleave implementation with explanation, executable examples, useful outputs, plots, images, tables, diagrams, and demonstrations of failure whenever they communicate the idea better than prose alone.
-
-These conventions matter most for published libraries with rendered documentation sites. Internal projects with no docs page can be looser: match the surrounding notebooks' style rather than imposing every rule here.
-
-# Notebooks generate modules
-
-The notebook is the source of truth: `nbdev-export` writes exported cells to the module named by `#| default_exp`, and generated `.py` files are never edited by hand. Each exported section carries a marker like `# %% ../nbs/04_usage.ipynb #a45f753a` naming its source notebook and cell, so module code always leads back to the cell to change. `__all__`, `_modidx.py`, and module docstrings likewise regenerate on export - renames and additions propagate automatically, so never hand-edit them.
-
-The module docstring comes from the notebook's opening markdown: the title cell's `>` description line, joined with every *exported* markdown cell after the H1 (a markdown cell whose first line is `#| export`). For a long module docstring, prefer one exported markdown cell per section over packing everything into the title blockquote; both work.
-
-Not every module must come from a notebook, and projects often mix the two deliberately. Choose per module: notebook-sourced when narrative earns its keep - public API whose docs page matters, code best explained through interleaved prose and examples, tests that double as documentation; plain `.py` when the code is dense interlocking mechanism, iterated quickly, and covered by pytest, where cell-by-cell narrative would add friction rather than clarity. Check the file, never the repo: a `# %%` autogen marker at the top means notebook-sourced, no marker means hand-written and edited directly, and `nbdev-export` only rewrites marked files. Tests follow the source form: example and test cells for notebook modules, `tests/*.py` pytest files for plain ones.
-
-# Choose the kind of page
-
-Decide which form of documentation the notebook provides:
-
-- A **tutorial** teaches through a guided learning experience.
-- A **how-to guide** helps a reader accomplish a practical task.
-- An **explanation** develops understanding of a focused topic.
-- A **reference** describes a technical component and its API.
-
-Do not mix these forms accidentally. A reference page can contain examples, but should remain easy to scan for symbols and behavior. A tutorial should advance in a purposeful sequence rather than becoming an API inventory. A how-to should solve its stated problem without expanding into a general course. An explanation should clarify concepts and trade-offs rather than masquerading as step-by-step instructions.
-
-# Open the notebook well
-
-Start with a markdown cell containing an H1 title and a blockquote subtitle:
-
-```markdown
-# Great title
-
-> A short description of what this page provides
-```
-
-Then introduce the page briefly. For a reference notebook, describe the component and orient the reader to its main symbols. For a tutorial or how-to, state what the reader will learn or accomplish. For an explanation, name the question or idea under discussion. Get to the subject quickly.
-
-Use headings to make longer pages navigable. H2 headings normally divide major concepts or groups of symbols. Lower-level headings can organize longer discussions, but avoid fragmenting a short narrative into many tiny sections.
-
-# Develop one idea at a time
-
-A productive nbdev rhythm is:
-
-1. Add the smallest useful implementation.
-2. Explain what it does and why it has that form.
-3. Demonstrate it with executable code.
-4. Assert the behavior where an assertion improves the example.
-5. Display the result a reader should notice.
-6. Continue to the next idea.
-
-This is a pattern, not a demand that every code cell contain one statement. A test or example cell may demonstrate several closely related facts. It must have a markdown introduction that tells the reader what the cell is about to establish. If that introduction becomes complicated, does not naturally introduce everything shown, or reads like an explanation of unrelated checks, the cell is doing too much and should be split. Conversely, prefer extending an existing example cell with a closely related check over adding a near-duplicate cell.
-
-Keep definitions small enough to understand in context. When a class benefits from incremental development, define its core first and add methods later with `@patch`. This lets each method appear beside its explanation and examples. Keep a class together when splitting it would make the API harder, not easier, to understand.
-
-# Prefer helpers with a public purpose
-
-A helper introduced to make the notebook's own examples or tests clearer may also be a useful part of the library. Internal use is often the first evidence that an abstraction is worth exposing, not a reason to hide it.
-
-Ask whether the helper gives users a concise, coherent operation they would otherwise need to reconstruct from lower-level internals. A good public helper:
-
-- removes repeated knowledge of internal data structures
-- gives a common operation a clear name and contract
-- makes examples and downstream code easier to read
-- provides one place to adapt callers when internals change
-- is useful independently of the implementation that first needed it
-
-For example, a function that constructs a canonical tool-call object may first appear while building a test fixture, but it is also useful to developers constructing those objects themselves. The fixture is its first consumer, not its justification for being private.
-
-Treat private helpers with some suspicion. An underscore is appropriate for implementation machinery that has no coherent independent contract, but not merely because a function was first written for internal use. If a helper is only useful to the library itself, consider whether it exposes an awkward internal design that should instead become a small, reusable public abstraction.
-
-# Make prose earn its place
-
-Markdown should explain information the code does not express well:
-
-- why an abstraction exists
-- what distinction matters
-- what behavior the next example demonstrates
-- why a design choice was made
-- what limitation or failure motivated the implementation
-- how a symbol relates to the rest of the API
-- which details are guarantees and which merely describe an example
-
-Do not translate code line by line into English. Do not write empty transitions such as “Now we test the function.” State the lesson instead: “A missing leaf returns `None`, so success status alone does not establish existence.”
-
-Place prose where it reads correctly in the generated page. An exported definition is normally followed by markdown explaining the symbol and introducing its first example.
-
-# Keep docstrings short
-
-Use a short docstring to say what a public symbol does. Put extended explanations, examples, trade-offs, warnings, and rich media in markdown cells, where they render properly and can include executable results.
-
-Use docments beside parameters and return values. They keep argument documentation close to the signature without repeating the signature in a long docstring.
-
-Use backticks around related symbols in prose. nbdev can turn symbol references into documentation links, so prefer symbol names over manually maintained documentation URLs.
-
-# Examples are documentation and tests
-
-Write every example as part of the page first, then make it verify behavior where useful. Good examples:
-
-- use realistic, comprehensible values
-- show the shortest path to the idea being taught
-- produce an informative representation or result
-- include direct assertions that reinforce rather than obscure the lesson
-- reuse objects introduced naturally earlier in the notebook
-- demonstrate important errors with executable failing examples
-
-Avoid test-suite plumbing in reader-facing cells. Dense mocks, deeply nested comprehensions, long setup blocks, and many unrelated assertions make poor documentation even when they test correctly. Extract a tiny helper when setup obscures the behavior. Hide necessary but unreadable checks rather than forcing them into the page narrative.
-
-Do not weaken a clear example merely to tolerate a future change that would invalidate its premise. If an example exists to show that an object contains a particular behavior, it should fail when that behavior disappears so the author notices and reassesses the page.
-
-A code cell often ends with the value that should be displayed. The final line might show an object’s representation, a table, a plot, an image, a diff, a count, or another visual result of what was created or tested. Assertions verify; the final expression teaches. Prefer a useful stored output over ending every cell silently.
-
-# Use notebook outputs deliberately
-
-Notebooks can communicate with more than text. Use plots, images, tables, diagrams, videos, terminal recordings, rich HTML, and custom representations when they make behavior easier to grasp.
-
-Design useful object representations when appropriate. A compact `_repr_markdown_`, table, plot, or structured summary can turn later examples into clear documentation without repeated formatting code.
-
-Stored outputs are part of the explanation. They show the reader what an example produced and preserve evidence from an executed notebook. Keep them focused and readable; do not dump large structures without saying what matters in them.
-
-# Show failures as behavior
-
-Errors are part of an API. When a failure mode matters, demonstrate it with executable code and an assertion such as `expect_fail`, rather than describing it only in prose. A reader should be able to see which input fails and what rule is being enforced.
-
-Keep failure examples focused. A large defensive test covering many hypothetical errors is less useful than one example for each important contract.
-
-# Let state flow downward
-
-Notebook state is sequential. Make that sequence easy to follow:
-
-- keep imports in dedicated import cells
-- define values shortly before they are first used
-- reuse established objects instead of rebuilding near-duplicates
-- avoid reassigning a name when later cells depend on its earlier meaning
-- move genuinely shared setup into a small, clearly introduced helper
-- end exploratory cells with the expression whose output records what was learned
-
-A reader should not need to search far upward to understand where a value came from. If several later examples rely on setup, introduce the setup explicitly and explain its role.
-
-The import rule is strict, and covers every cell including tests: the docs build executes each cell that contains an import in a fresh namespace where the other cells have not run, so a cell mixing imports with other code either breaks the build with a NameError or silently runs at documentation time.
-
-# Use directives purposefully
-
-`#| default_exp` selects the generated module. `#| export` marks implementation for export. Private underscore-prefixed helpers may be exported with their public consumers without becoming part of the public API. `#| hide` keeps necessary but distracting material off the rendered page. `#| eval: false` is for examples that genuinely must not run automatically, not for suppressing broken cells.
-
-Directives affect both execution and documentation, so apply them according to the role of the whole cell. In particular, an unevaluated cell cannot create state required by later evaluated cells - so newly marking a cell `eval: false` means cascading the directive to the cells that depend on it.
-
-# Prefer executable evidence
-
-Whenever practical, show rather than claim:
-
-- display the object instead of describing its representation
-- run the transformation instead of paraphrasing the result
-- draw the plot instead of only discussing its shape
-- trigger the error instead of merely listing it
-- compare outputs when a distinction matters
-
-Executable evidence keeps documentation synchronized with behavior. Assertions turn important examples into regression tests, while visible outputs keep those tests useful to human readers.
-
-# Common authoring failures
-
-Avoid these patterns:
-
-- a large implementation followed much later by one large test section
-- several abstractions introduced before any is demonstrated
-- markdown that merely narrates the next line of code
-- long docstrings carrying material better expressed in notebook cells
-- imports mixed into example or test cells
-- repeated setup copied across examples
-- reader-facing cells dominated by mocks or cleanup machinery
-- many unrelated checks under one vague introduction
-- assertions that hide the result the reader needs to see
-- pages with no clear reader, purpose, or documentation form
-- descriptions of behavior that could be demonstrated directly
-- large outputs with no guidance about what to notice
-
-The governing test is simple: the notebook should be pleasant and informative to read, convincing when executed, and useful as the source of the library it documents.
-"""