nbdev 3.3.1__tar.gz → 3.3.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.1
+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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.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.1 → nbdev-3.3.2/nbdev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.1
+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.1 → 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.1 → 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.1/nbdev/__init__.py

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

nbdev-3.3.1/nbdev/skill.py

@@ -1,56 +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 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 deliberately: notebooks where narrative earns its keep (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: view its first few lines - 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 deliberately 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: Jupyter collapses sections by cell.
-
-# Develop one idea at a time
-
-The rhythm: 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 ("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; the final expression teaches: end cells with the value worth displaying, 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. Show rather than claim; executable evidence keeps documentation synchronized with behavior.
-
-# 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` - 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: it failed before the change and passed after. Re-read the touched section as a reader would, against the conventions above - style damage fails silently: tests pass, export succeeds, and the harm only shows on the docs page.
-
-The governing test: pleasant and informative to read, convincing when executed, useful as the source of the library it documents.
-"""