nbdev 3.3.21__tar.gz → 3.3.22__tar.gz

{nbdev-3.3.21/nbdev.egg-info → nbdev-3.3.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.21
+Version: 3.3.22
 Summary: Create delightful software with Jupyter Notebooks
 Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
 License-Expression: Apache-2.0

{nbdev-3.3.21 → nbdev-3.3.22}/nbdev/__init__.py

@@ -4,9 +4,9 @@ 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.moddocs`: # Module docs: creating them from existing notebooks
-- `nbdev.skill`: Author nbdev notebooks as source, documentation, examples, and tests. Ensure this guidance is in context before any notebook edit."""
+- `nbdev.skill`: Write, read and review nbdev notebooks as source, documentation, examples and tests. You MUST read this before any work on a project with notebooks."""
 
-__version__ = "3.3.21"
+__version__ = "3.3.22"
 
 from .doclinks import nbdev_export
 from .showdoc import show_doc

{nbdev-3.3.21 → nbdev-3.3.22}/nbdev/_modidx.py

@@ -364,6 +364,7 @@ d = { 'settings': { 'branch': 'main',
             'nbdev.serve': { 'nbdev.serve._is_qpy': ('api/serve.html#_is_qpy', 'nbdev/serve.py'),
                              'nbdev.serve._keep_file': ('api/serve.html#_keep_file', 'nbdev/serve.py'),
                              'nbdev.serve._proc_file': ('api/serve.html#_proc_file', 'nbdev/serve.py'),
+                             'nbdev.serve._rm_stale': ('api/serve.html#_rm_stale', 'nbdev/serve.py'),
                              'nbdev.serve.proc_nbs': ('api/serve.html#proc_nbs', 'nbdev/serve.py')},
             'nbdev.showdoc': { 'nbdev.showdoc.BasicMarkdownRenderer': ('api/showdoc.html#basicmarkdownrenderer', 'nbdev/showdoc.py'),
                                'nbdev.showdoc.BasicMarkdownRenderer._repr_markdown_': ( 'api/showdoc.html#basicmarkdownrenderer._repr_markdown_',

{nbdev-3.3.21 → nbdev-3.3.22}/nbdev/maker.py

@@ -191,7 +191,9 @@ def _retr_mdoc(cells, nb_path=None):
     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()
-    return f'"""{mdoc}"""\n\n' if mdoc else ''
+    if not mdoc: return ''
+    r = 'r' if '\\' in mdoc else ''
+    return f'{r}"""{mdoc}"""\n\n'
 
 # %% ../nbs/api/02_maker.ipynb #cdd205d6
 @patch

{nbdev-3.3.21 → nbdev-3.3.22}/nbdev/quarto.py

@@ -23,6 +23,7 @@ from fastcore.shutil import rmtree,move,copytree
 from fastcore.meta import delegates
 from .serve import proc_nbs,_proc_file
 from . import serve_drv
+from .quarto_render import render_quarto
 import yaml
 
 # %% ../nbs/api/14_quarto.ipynb #aae2d2be-ad03-4536-bf70-c4575f39cea3
@@ -138,7 +139,7 @@ def nbdev_sidebar(
     yml = yaml.dump(parsed_struct, Dumper=IndentDumper, sort_keys=False)
 
     if printit: return print(yml)
-    yml_path.write_text(yml)
+    if not yml_path.exists() or yml_path.read_text() != yml: yml_path.write_text(yml)
 
 # %% ../nbs/api/14_quarto.ipynb #aabf2f15
 _quarto_yml="""project:
@@ -189,7 +190,8 @@ def refresh_quarto_yml():
     vals = {k:cfg[k] for k in ['title', 'description', 'branch', 'git_url', 'doc_host', 'doc_baseurl']}
     vals['doc_path'] = cfg.doc_path.name
     if 'title' not in vals: vals['title'] = vals['lib_name']
-    ny.write_text(_nbdev_yml.format(**vals))
+    text = _nbdev_yml.format(**vals)
+    if not ny.exists() or ny.read_text() != text: ny.write_text(text)
     qy = cfg.nbs_path/'_quarto.yml'
     if 'custom_quarto_yml' in cfg: print("NB: `_quarto.yml` is no longer auto-updated. Remove `custom_quarto_yml` from `pyproject.toml`")
     if qy.exists() and not str2bool(cfg.get('custom_quarto_yml', True)): qy.unlink()
@@ -335,11 +337,11 @@ def _fix_quarto_nav(doc_path):
 @delegates(_nbglob_docs)
 def nbdev_docs(
     path:str=None, # Path to notebooks
-    n_workers:int=defaults.cpus,  # Number of workers
+    n_workers:int=defaults.cpus,  # Preprocessing and Quarto workers (0 or 1: serial)
     **kwargs):
     "Create Quarto docs and README.md"
     cache,cfg,path = _pre_docs(path, n_workers=n_workers, **kwargs)
-    _sprun(f'cd "{cache}" && quarto render --no-cache')
+    render_quarto(cache, cache/cfg.doc_path.name, n_workers=n_workers)
     nbdev_readme.__wrapped__(path=path, chk_time=True)
     nbdev_contributing.__wrapped__(path=path, chk_time=True)
     shutil.rmtree(cfg.doc_path, ignore_errors=True)
@@ -382,11 +384,15 @@ def nbdev_preview(
     port:int=None, # The port on which to run preview
     host:str=None, # The host on which to run preview
     no_browser:bool=False, # Do not open a browser
-    n_workers:int=defaults.cpus,  # Number of workers
+    render:bool=False, # Render all pages before previewing
+    n_workers:int=defaults.cpus,  # Preprocessing and Quarto workers (0 or 1: serial)
     **kwargs):
     "Preview docs locally"
     os.environ['QUARTO_PREVIEW']='1'
     cache,cfg,path = _pre_docs(path, n_workers=n_workers, **kwargs)
+    site = cache/cfg.doc_path.name
+    if not (render or site.exists()) and cfg.doc_path.exists(): copytree(cfg.doc_path, site)
+    if render or not site.exists(): render_quarto(cache, site, n_workers=n_workers)
     xtra = []
     if port: xtra += ['--port', str(port)]
     if host: xtra += ['--host', host]
@@ -399,5 +405,4 @@ def nbdev_preview(
             except: traceback.print_exc()
 
     os.chdir(cache)
-    xtra = xtra or []
     with fs_watchdog(_f, path): subprocess.run(['quarto','preview']+xtra)

nbdev-3.3.22/nbdev/quarto_render.py

@@ -0,0 +1,71 @@
+"Parallel Quarto website rendering in isolated project copies."
+
+import json, shutil, subprocess, tempfile
+from pathlib import Path
+from xml.etree import ElementTree as ET
+from fastcore.parallel import parallel
+from fastcore.utils import defaults
+
+
+def _quarto(path, *args):
+    res = subprocess.run(['quarto', *map(str, args)], cwd=path, capture_output=True, text=True)
+    if res.returncode: raise RuntimeError(res.stderr or res.stdout or f'Quarto exited with status {res.returncode}')
+    return res.stdout
+
+
+def _render_batch(job):
+    path, inputs, output = job
+    _quarto(path, 'render', *inputs, '--no-cache', '--no-clean', '--output-dir', output)
+    return output
+
+
+def _merge_site(outputs, dest):
+    search, urls, homepage = {}, {}, None
+    sitemap = None
+    for output in outputs:
+        idx = output/'index.html'
+        if idx.exists() and (homepage is None or 'http-equiv="refresh"' not in idx.read_text()): homepage = idx
+        if (output/'search.json').exists():
+            for entry in json.loads((output/'search.json').read_text()): search[entry['href']] = entry
+        if (output/'sitemap.xml').exists():
+            sitemap = ET.parse(output/'sitemap.xml')
+            for entry in sitemap.getroot(): urls[entry.find('{*}loc').text] = entry
+        shutil.copytree(output, dest, dirs_exist_ok=True)
+    if homepage: shutil.copy2(homepage, dest/'index.html')
+    if search: (dest/'search.json').write_text(json.dumps(list(search.values())))
+    if sitemap is not None:
+        sitemap.getroot()[:] = urls.values()
+        ET.register_namespace('', 'http://www.sitemaps.org/schemas/sitemap/0.9')
+        sitemap.write(dest/'sitemap.xml', encoding='utf-8', xml_declaration=True)
+
+
+def render_quarto(path, output_dir, n_workers=defaults.cpus):
+    "Render a project, parallelizing website pages with isolated Quarto workers."
+    path, output_dir = Path(path).resolve(), Path(output_dir).resolve()
+    if output_dir == path or output_dir in path.parents: raise ValueError('Output directory must not contain the project')
+    if n_workers <= 1:
+        _quarto(path, 'render', '--no-cache', '--output-dir', output_dir)
+        return
+    info = json.loads(_quarto(path, 'inspect'))
+    project = info['config']['project']
+    website = info['config'].get('website', {})
+    if project['type'] != 'website' or project.get('pre-render') or project.get('post-render') or website.get('llms-txt'):
+        return render_quarto(path, output_dir, n_workers=1)
+    inputs = [str(Path(p).relative_to(path)) for p in info['files']['input']]
+    if len(inputs) < 2: return render_quarto(path, output_dir, n_workers=1)
+    n_workers = min(n_workers, len(inputs))
+    print(f'Rendering {len(inputs)} pages with {n_workers} Quarto workers')
+    excluded = {path/'.quarto', (path/project.get('output-dir', '_site')).resolve(), output_dir}
+    def ignore(src, names): return [n for n in names if Path(src)/n in excluded]
+    with tempfile.TemporaryDirectory(prefix='nbdev-quarto-') as tmp:
+        jobs = []
+        for i in range(n_workers):
+            worker = Path(tmp)/str(i)
+            shutil.copytree(path, worker, ignore=ignore)
+            jobs.append((worker, inputs[i::n_workers], Path(tmp)/f'output-{i}'))
+        outputs = parallel(_render_batch, jobs, n_workers=n_workers, threadpool=True)
+        merged = Path(tmp)/'merged'
+        _merge_site(outputs, merged)
+        if output_dir.exists(): shutil.rmtree(output_dir)
+        output_dir.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(merged, output_dir)

{nbdev-3.3.21 → nbdev-3.3.22}/nbdev/serve.py

@@ -38,15 +38,12 @@ def _is_qpy(path:Path):
         if vl[0]=='---' and vl[-1]=='---': return '\n'.join(vl[1:-1])
 
 # %% ../nbs/api/17_serve.ipynb #abc3835a
-def _proc_file(s, cache, path, mtime=None):
+def _proc_file(s, cache, path):
     skips = ('_proc', '_docs', '_site', 'pyproject.toml')
     if not s.is_file() or any(o[0]=='.' or o in skips for o in s.parts): return
     d = cache/s.relative_to(path)
     if s.suffix=='.py': d = d.with_suffix('')
-    if d.exists():
-        dtime = d.stat().st_mtime
-        if mtime: dtime = max(dtime, mtime)
-        if s.stat().st_mtime<=dtime: return
+    if d.exists() and s.stat().st_mtime<=d.stat().st_mtime: return
 
     d.parent.mkdir(parents=True, exist_ok=True)
     if s.suffix=='.ipynb': return s,d,FilterDefaults
@@ -60,6 +57,15 @@ def _keep_file(f:Path, file_glob='', file_re=''):
     if f.suffix!='.ipynb': return True
     return (not file_glob or fnmatch(f.name, file_glob)) and (not file_re or bool(re.search(file_re, f.name)))
 
+# %% ../nbs/api/17_serve.ipynb #ff47fad5
+def _rm_stale(cache:Path, path:Path):
+    "Remove pages in `cache` whose source in `path` no longer exists"
+    for d in list(cache.rglob('*')):
+        rel = d.relative_to(cache)
+        if d.suffix not in ('.ipynb','.qmd','.md') or any(o[0]=='.' for o in rel.parts): continue
+        s = path/rel
+        if not (s.exists() or s.with_name(s.name+'.py').exists()): d.unlink()
+
 # %% ../nbs/api/17_serve.ipynb #14463227
 @delegates(nbglob_cli)
 def proc_nbs(
@@ -77,6 +83,7 @@ def proc_nbs(
     if file_glob or file_re: files = files.filter(_keep_file, file_glob=file_glob, file_re=file_re)
     if (path/'_quarto.yml').exists(): files.append(path/'_quarto.yml')
     if (path/'_brand.yml').exists(): files.append(path/'_brand.yml')
+    files.extend(nbglob(path, func=Path, file_glob='_metadata.y*ml', skip_file_re='^[.]'))
     if (path/'_extensions').exists(): files.extend(nbglob(path/'_extensions', func=Path, file_glob='', file_re='', skip_file_re='^[.]'))
 
     # If pyproject.toml or filter script newer than cache folder modified, delete cache
@@ -85,8 +92,9 @@ def proc_nbs(
     cache_mtime = cache.stat().st_mtime
     if force or (cache.exists() and cache_mtime<chk_mtime): rmtree(cache)
     (cache/'_quarto.yml').unlink(missing_ok=True)  # single-doc renders strip the staged copy in place (`_strip_sidebar`), so always restage it
+    _rm_stale(cache, path)
 
-    files = files.map(_proc_file, mtime=cache_mtime, cache=cache, path=path).filter()
+    files = files.map(_proc_file, cache=cache, path=path).filter()
     kw = {} if in_notebook() else {'method':'spawn'}
     parallel(nbdev.serve_drv.main, files, n_workers=n_workers, pause=0.01, **kw)
     if cache.exists(): cache.touch()

nbdev-3.3.22/nbdev/skill.py

@@ -0,0 +1,82 @@
+"""Write, read and review nbdev notebooks as source, documentation, examples and tests. You MUST read this before any work on a project with notebooks.
+
+# Source
+
+Write notebooks to be read top-to-bottom, interleaving implementation, explanation, examples, outputs, and failure demonstrations. Follow these conventions in published libraries. In internal projects, match the surrounding notebooks.
+
+Check the file, not the repo: `# AUTOGENERATED! DO NOT EDIT!` names the source notebook; `# %% ../nbs/04_usage.ipynb #a45f753a` identifies the source cell. Edit that notebook, never generated modules, `__all__`, `_modidx.py`, or module docstrings; `nbdev-export` regenerates them. Unmarked modules are hand-written. Use notebooks to teach the API through narrative and examples, and plain `.py` for dense mechanism iterated under pytest (rarely; never add pytests to a project without them unless asked). Lessons test notebook code. Test plain modules in `tests/*.py`.
+
+Understand and review work through the notebooks and their `git diff`, never generated modules. Those lack the prose, examples and tests.
+
+For project-level questions, read `nbs/index.ipynb`, the source of README.md; regenerate with `nbdev-readme` after changes.
+
+# Structure and authoring
+
+Choose tutorial, how-to, explanation, or reference. Open with an H1 title cell and `>` subtitle, then a brief introduction. Use H2s for major concepts without fragmenting short narratives. Each heading belongs in its own markdown cell so Jupyter can collapse sections.
+
+Before changing a notebook, read the whole notebook or a summary of every cell. For a new notebook, read a role model such as claudette's `00_core.ipynb` to learn the literate form.
+
+Develop one idea at a time: a small implementation, its explanation, and a lesson if it's a substantive API. Introduce each lesson in markdown; split it when the introduction becomes complicated. Extend existing examples rather than adding near-duplicates. Build classes with `@patch` beside each method's explanation unless that obscures the API.
+
+When new behavior needs a lesson, choose its narrative position, write the lesson first, run preceding cells as needed, and see it fail. Add its markdown introduction and implementation above it, then run both to see it pass. For bugs, revise an existing example to exercise the failing path; if no revision fits, add an assertion to it. If no documented behavior changes, change no lesson cells. Never add a cell merely to witness a fix.
+
+Read existing examples before experimenting. Explore in the notebook, not in a separate kernel check; keep useful explorations as lessons and delete the rest. Always try to leave a notebook better than you found it.
+
+Reserve underscore names for machinery without a coherent independent contract, not for everything used only internally. If a helper is only useful internally, the design is often awkward.
+
+# Prose and module documentation
+
+In markdown, explain rationale, distinctions and guarantees. Don't narrate code line by line or write filler transitions. Place markdown where it reads correctly on the generated page, normally after the definition. Use short symbol docstrings, parameter/return docments beside signatures, and backticked symbol names for nbdev links. Extended explanation, examples, and warnings belong in markdown.
+
+`nbdev-export` builds the module docstring from the title's `>` description and exported markdown after the H1. Use one exported markdown cell per major section for long docstrings. `doc(module)` lists the functions. In module prose, explain only shared constraints and workflows.
+
+`#| exportd` includes a code cell as fenced source in the module docstring, not module code. Use compact runnable demos after their required definitions; end the preceding exported summary with a colon. Unexported definitions between the summary and demo don't appear in the docstring.
+
+Check claims by running code before documenting them; preview assembly with `nbdev.export.nb_mdoc`. `nbdev-export` lists a module in package documentation and `llms.txt` if its docstring has more than the default summary. Only extend docstrings of modules read on their own. Export the opening paragraphs of `index.ipynb` for the package intro.
+
+# Lesson cells
+
+A notebook guides a reader through what the code does. Readability comes first.
+
+Every substantive API needs a lesson. Basic functionality outside the API, with little logic, generally doesn't.
+
+Explain with code and its displayed output. When a displayed value is also worth testing, assign it, test it, then show it. Test results that are the point of the code, not incidentals such as formatting.
+
+Show an error only when readers are likely to hit it.
+
+A cell that serves a test instead of a reader doesn't belong on the page. Signs include setup that exists only so a check can run safely, and checks on glue code. Usually, remove such a test. If it checks substantive logic, move it to a `#| hide` cell or to pytest. Discuss such changes carefully.
+
+Write page content: realistic values, minimal setup, reused objects, and direct assertions that support the lesson. Show evidence with compact `_repr_markdown_` or structured summaries, plots, tables, images or HTML. Explain what matters in large outputs and keep stored results focused.
+
+Use `fastcore.test` assertions and `expect_fail` in ordinary code cells. Keep check plumbing, mocks, dense comprehensions, and long setup out of reader-facing examples: extract a small helper or hide the check. Use `nbdev-test --file-re` to run several named notebooks in parallel.
+
+Consider a rewrite when you see these:
+
+- Split commented examples into prose and code. Split numbered steps into markdown/code pairs. Keep comments that state constraints code cannot show.
+- Replace a sentence-wrapped `print` with prose and a displayed value, and a final `print(x)` with bare `x`.
+- Split reassignment stages and blank-line groups into cells, each with its own introduction.
+- In near-duplicate examples, explain the argument that differs. Don't repeat the setup.
+- Show errors with `expect_fail`, not `try`/`except`. Move long docstrings to markdown.
+- Resolve TODO/FIXME example comments or move them to issues.
+
+# State and execution
+
+Define values near first use, introduce shared setup, reuse established objects, and don't reassign names later cells depend on. End exploratory cells with the expression recording what was learned when useful.
+
+Keep imports in dedicated cells, including in lessons: docs builds execute import-containing cells in fresh namespaces, so mixing imports with state-dependent code can fail or run code at documentation time.
+
+Stored outputs are generated and may be stale during editing. Don't stop work, clear them by hand, or edit notebook JSON because they no longer match the source. At PR time, regenerate them with `nbdev-test --save` if the project keeps saved outputs.
+
+# Directives and nbdev v3
+
+- `#| default_exp` names the generated module; `#| export` includes a cell there. Exported underscore helpers need not be public.
+- `#| hide` hides distracting necessities from the page.
+- `#| eval: false` is for code that must not run, not broken code. Later cells can't use its state.
+- Directives may instead be metadata: `{"nbdev": {"export": "true"}}`. nbdev reads both; `fastcore.nbio.mk_cell(...).directives` merges them with content winning conflicts.
+
+nbdev v3 (Jan 2026) uses `pyproject.toml`, not `settings.ini`: metadata in `[project]`, nbdev settings in `[tool.nbdev]` (default `nbs_path='nbs'`, `doc_path='_docs'`), version in `__init__.py` via `dynamic = ["version"]`, and `_modidx` in `[project.entry-points.nbdev]`. CLIs use hyphens (`nbdev-export`, `nbdev-test`); Python names retain underscores. GitHub actions are `fastai/workflows/nbdev3-ci` and `quarto-ghp3`.
+
+# Finish
+
+Revise affected prose, displays, and assertions together; changed assertions must fail on old code and pass on new. Re-read the touched narrative for readability. Run `nbdev-test <nb>`.
+"""

{nbdev-3.3.21 → nbdev-3.3.22/nbdev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.21
+Version: 3.3.22
 Summary: Create delightful software with Jupyter Notebooks
 Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
 License-Expression: Apache-2.0

{nbdev-3.3.21 → nbdev-3.3.22}/nbdev.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ nbdev/process.py
 nbdev/processors.py
 nbdev/qmd.py
 nbdev/quarto.py
+nbdev/quarto_render.py
 nbdev/release.py
 nbdev/scrubmagics.py
 nbdev/serve.py
@@ -34,4 +35,5 @@ nbdev.egg-info/SOURCES.txt
 nbdev.egg-info/dependency_links.txt
 nbdev.egg-info/entry_points.txt
 nbdev.egg-info/requires.txt
-nbdev.egg-info/top_level.txt
+nbdev.egg-info/top_level.txt
+tests/test_quarto_render.py

nbdev-3.3.22/tests/test_quarto_render.py

@@ -0,0 +1,54 @@
+import json, shutil, subprocess, pytest
+from xml.etree import ElementTree as ET
+from fastcore.test import test_eq as teq
+from nbdev.quarto_render import render_quarto
+
+
+@pytest.mark.skipif(not shutil.which('quarto'), reason='requires Quarto')
+def test_website(tmp_path):
+    root = tmp_path/'source'
+    root.mkdir()
+    (root/'_quarto.yml').write_text(r'''project:
+  type: website
+website:
+  title: Parallel render
+  site-url: https://example.com/
+  sidebar:
+    contents: [index.qmd, alpha.qmd, beta.qmd]
+format:
+  html: default
+  commonmark: default
+execute:
+  enabled: false
+''')
+    for name in ('index', 'alpha', 'beta'):
+        (root/f'{name}.qmd').write_text(fr'''---
+title: {name}
+---
+## Detail
+
+Page {name}. [Alpha](alpha.qmd#detail). [Download](data.txt).
+''')
+    (root/'data.txt').write_text('shared resource')
+    serial, parallel = tmp_path/'serial', tmp_path/'parallel'
+    render_quarto(root, serial, n_workers=1)
+    render_quarto(root, parallel, n_workers=2)
+    search = lambda d: {e['href']: e['text'] for e in json.loads((d/'search.json').read_text())}
+    urls = lambda d: {e.text for e in ET.parse(d/'sitemap.xml').findall('.//{*}loc')}
+    teq(search(serial), search(parallel))
+    teq(urls(serial), urls(parallel))
+    teq(len(urls(parallel)), 3)
+    for name in ('index', 'alpha', 'beta'):
+        html = (parallel/f'{name}.html').read_text()
+        assert 'alpha.html#detail' in html and 'data.txt' in html
+        assert (parallel/f'{name}.md').exists()
+    teq((parallel/'data.txt').read_text(), 'shared resource')
+    assert (parallel/'site_libs').is_dir()
+    assert 'http-equiv="refresh"' not in (parallel/'index.html').read_text()
+    (root/'beta.qmd').write_text('---\ntitle: beta\n---\n## Detail\n\nUpdated beta.')
+    subprocess.run(['quarto', 'render', 'beta.qmd', '--quiet', '--output-dir', str(parallel)], cwd=root, check=True)
+    teq(set(search(serial)), set(search(parallel)))
+    assert 'Updated beta.' in search(parallel)['beta.html#detail']
+    (root/'beta.qmd').write_text('---\nfilters: [missing.lua]\n---\nBroken.')
+    with pytest.raises(RuntimeError, match='missing.lua'): render_quarto(root, parallel, n_workers=2)
+    assert 'Updated beta.' in search(parallel)['beta.html#detail']

nbdev-3.3.21/nbdev/skill.py

@@ -1,70 +0,0 @@
-"""Author nbdev notebooks as source, documentation, examples, and tests. Ensure this guidance is in context before any notebook edit.
-
-# Source
-
-Write notebooks to be read top-to-bottom, interleaving implementation, explanation, examples, outputs, and failure demonstrations. These conventions target published libraries; match surrounding notebooks in internal projects.
-
-Check the file, not the repo: `# AUTOGENERATED! DO NOT EDIT!` names the source notebook; `# %% ../nbs/04_usage.ipynb #a45f753a` identifies the source cell. Edit that notebook, never generated modules, `__all__`, `_modidx.py`, or module docstrings; `nbdev-export` regenerates them. Unmarked modules are hand-written. Use notebooks where narrative/examples teach the API, plain `.py` for dense mechanism iterated under pytest (which should be very rare; never add pytests to a project that doesn't have any, unless explicitly requested). Tests follow source form: lesson cells for notebooks, `tests/*.py` for plain modules.
-
-For project-level questions, read `nbs/index.ipynb`, the source of README.md; regenerate with `nbdev-readme` after changes.
-
-# Structure and authoring
-
-Choose tutorial, how-to, explanation, or reference. Open with an H1 title cell and `>` subtitle, then a brief introduction. Use H2s for major concepts without fragmenting short narratives. Each heading belongs in its own markdown cell so Jupyter can collapse sections.
-
-Before changing a notebook, read the whole notebook or a summary of every cell. For a new notebook, read a role model such as claudette's `00_core.ipynb` to learn the literate form.
-
-Develop one idea at a time: small implementation, explanation, executable lesson, assertions where useful. Introduce each lesson in markdown; split it when the introduction becomes complicated. Extend existing examples rather than adding near-duplicates. Build classes with `@patch` beside each method's explanation unless that obscures the API.
-
-For new behavior, choose its narrative position, write the lesson first, run preceding cells as needed, and see it fail. Add its markdown introduction and implementation above it, then run implementation and lesson to see it pass. For bugs, revise an existing example to exercise the failing path; if no revision fits, add an assertion to it. If no documented behavior changes, change no lesson cells. Never add a cell merely to witness a fix.
-
-Read existing examples before experimenting. Explore in the notebook, not in a separate kernel check; retain useful explorations as lessons and delete those that teach nothing worth keeping. Always try to leave a notebook better than you found it.
-
-Reserve underscore names for machinery without a coherent independent contract. Internal use can justify exposing an abstraction; helpers useful only internally may indicate awkward design.
-
-# Prose and module documentation
-
-Markdown explains rationale, distinctions, and guarantees, not code line-by-line or empty transitions. Place it where it reads correctly on the generated page, normally after the definition. Use short symbol docstrings, parameter/return docments beside signatures, and backticked symbol names for nbdev links. Extended explanation, examples, and warnings belong in markdown.
-
-The module docstring combines the title's `>` description with exported markdown after H1. Use one exported markdown cell per major section for long docstrings. Since `doc(module)` also lists functions, module prose should teach shared constraints and workflows, not repeat individual API documentation.
-
-`#| exportd` includes a code cell as fenced source in the module docstring, not module code. Use compact runnable demos after their required definitions; end the preceding exported summary with a colon. Only exported cells join the docstring, so definitions between that summary and demo do not separate them there.
-
-Check claims by running code before documenting them; preview assembly with `nbdev.export.nb_mdoc`. A docstring beyond the default summary causes `nbdev-export` to include the module in package documentation and `llms.txt`; write these summaries for modules meant to be read independently. Export the opening paragraphs of `index.ipynb` for the package intro.
-
-# Lesson cells
-
-Write page content, not standalone test cells (except rare hidden checks): realistic values, minimal setup, reused objects, and direct assertions that support the lesson. End lesson cells with an informative displayed value when there is something useful to show. Compact `_repr_markdown_` or structured summaries can make later examples readable; plots, tables, images, and HTML also provide evidence. Explain what matters in large outputs and keep stored results focused.
-
-Use `fastcore.test` assertions and `expect_fail` in ordinary code cells, with one focused error example per contract. Keep check plumbing, mocks, dense comprehensions, and long setup out of reader-facing examples: extract a small helper or hide the check. Use `nbdev-test --file-re` for running >1 named notebook, since they'll run in parallel.
-
-Review these as rewrite signals, not absolute rules:
-
-- Comments often mark a split into prose and code; numbered steps suggest separate markdown/code pairs. Keep comments that state constraints code cannot show.
-- A sentence-wrapped `print` belongs in prose plus a displayed value; final `print(x)` loses rich repr compared with bare `x`.
-- Reassignments through stages can hide useful intermediate displays; blank-line groups suggest cell boundaries with their own introductions.
-- Near-duplicate examples should make the differing argument the narrative, rather than repeat setup.
-- Error-demonstration `try`/`except` usually wants `expect_fail`; long docstrings want markdown.
-- Resolve TODO/FIXME example comments or move them to issues.
-
-# State and execution
-
-Define values near first use, introduce shared setup, reuse established objects, and don't reassign names later cells depend on. End exploratory cells with the expression recording what was learned when useful.
-
-Keep imports in dedicated cells, including in lessons: docs builds execute import-containing cells in fresh namespaces, so mixing imports with state-dependent code can fail or run code at documentation time.
-
-Stored outputs are generated artifacts and may be stale during editing. Do not stop, clear them manually, or manipulate notebook JSON because output no longer matches source. At PR time, regenerate with `nbdev-test --save` when the project needs saved outputs updated.
-
-# Directives and nbdev v3
-
-- `#| default_exp` names the generated module; `#| export` includes a cell there. Exported underscore helpers need not join the public API.
-- `#| hide` hides distracting necessities from the page.
-- `#| eval: false` is for code that must not run, not broken code; it cannot supply state to evaluated cells.
-- Directives may instead be metadata: `{"nbdev": {"export": "true"}}`. The toolchain honors both; `mk_cell(...).directives` merges them with content winning conflicts.
-
-nbdev v3 (Jan 2026) uses `pyproject.toml`, not `settings.ini`: metadata in `[project]`, nbdev settings in `[tool.nbdev]` (default `nbs_path='nbs'`, `doc_path='_docs'`), version in `__init__.py` via `dynamic = ["version"]`, and `_modidx` in `[project.entry-points.nbdev]`. CLIs use hyphens (`nbdev-export`, `nbdev-test`); Python names retain underscores. GitHub actions are `fastai/workflows/nbdev3-ci` and `quarto-ghp3`.
-
-# Finish
-
-Revise affected prose, displays, and assertions together; changed assertions must fail on old code and pass on new. Re-read the touched narrative for readability: tests cannot catch documentation damage. Run `nbdev-test <nb>`.
-"""