nbdev 3.3.24__tar.gz → 3.3.26__tar.gz

{nbdev-3.3.24/nbdev.egg-info → nbdev-3.3.26}/PKG-INFO

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

@@ -6,7 +6,7 @@ Modules:
 - `nbdev.moddocs`: # Module docs: creating them from existing notebooks
 - `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.24"
+__version__ = "3.3.26"
 
 from .doclinks import nbdev_export
 from .showdoc import show_doc

{nbdev-3.3.24 → nbdev-3.3.26}/nbdev/quarto.py

@@ -23,7 +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
+from .quarto_render import render_quarto, quarto_stale
 import yaml
 
 # %% ../nbs/api/14_quarto.ipynb #aae2d2be-ad03-4536-bf70-c4575f39cea3
@@ -75,7 +75,7 @@ def _sort(a):
 
 _def_file_re = r'\.(?:ipynb|qmd|html)$'
 
-@delegates
+@delegates(nbglob_cli)
 def _nbglob_docs(
     path:str=None, # Path to notebooks
     file_glob:str=None, # Only include files matching glob    
@@ -214,9 +214,8 @@ def _pre_docs(path=None, n_workers:int=defaults.cpus, **kwargs):
     path = Path(path).absolute() if path else cfg.nbs_path
     if not (path/'nbdev.yml').exists(): path = cfg.nbs_path  # given a project root, fall back to its configured nbs
     os.chdir(cfg.config_path)  # bare `get_config()` runs downstream (including in render workers), so anchor the cwd
-    _chk_nbdev_yml(path)
-    _ensure_quarto()
     refresh_quarto_yml()
+    _ensure_quarto()
     import nbdev.doclinks
     nbdev.doclinks._build_modidx()
     nbdev_sidebar.__wrapped__(path=path, **kwargs)
@@ -290,7 +289,9 @@ def nbdev_readme(
     _strip_sidebar(cache)  # to avoid rendering whole website
     for f in _readme_cands(cache, cfg):
         if f.exists(): f.unlink() # remove stale renders from either quarto layout
-    _sprun(f'cd "{cache}" && quarto render "{cache/cfg.readme_nb}" -o README.md -t gfm --no-execute -M wrap:preserve')
+    from nbdev import readme_filter
+    filt = fr""" -M 'filters:["{readme_filter.__file__}"]'""" if cfg.doc_host else ''
+    _sprun(f'cd "{cache}" && quarto render "{cache/cfg.readme_nb}" -o README.md -t gfm --no-execute -M wrap:preserve{filt}')
 
     _save_cached_readme(cache, cfg)
 
@@ -390,7 +391,7 @@ def nbdev_preview(
     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)
+    if render or not site.exists() or quarto_stale(cache, site): render_quarto(cache, site, n_workers=n_workers)
     xtra = []
     if port: xtra += ['--port', str(port)]
     if host: xtra += ['--host', host]

{nbdev-3.3.24 → nbdev-3.3.26}/nbdev/quarto_render.py

@@ -1,10 +1,9 @@
 "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
+from fastcore.utils import *
 
 
 def _quarto(path, *args):
@@ -13,6 +12,17 @@ def _quarto(path, *args):
     return res.stdout
 
 
+def quarto_stale(path, output_dir):
+    "Whether a page's HTML output is missing or older than its processed source."
+    path, output_dir = Path(path).resolve(), Path(output_dir).resolve()
+    info = loads(_quarto(path, 'inspect'))
+    for name,entry in info['fileInformation'].items():
+        p = Path(name)
+        output = output_dir/p.parent/(entry['metadata'].get('output-file') or p.with_suffix('.html').name)
+        if not output.exists() or (path/p).stat().st_mtime>output.stat().st_mtime: return True
+    return False
+
+
 def _render_batch(job):
     path, inputs, output = job
     _quarto(path, 'render', *inputs, '--no-cache', '--no-clean', '--output-dir', output)

nbdev-3.3.26/nbdev/readme_filter.py

@@ -0,0 +1,36 @@
+r"Pandoc filter for README documentation links."
+
+from fastcore.utils import *
+from fastcore.script import *
+from nbdev.config import *
+from urllib.parse import urlsplit, urlunsplit, urljoin
+
+
+def doc_link(target, base, nbdir='.'):
+    "Convert a relative documentation link to its hosted URL."
+    u = urlsplit(target)
+    p = Path(u.path)
+    if u.scheme or u.netloc or p.suffix not in ('.ipynb', '.qmd', '.html', '.txt'): return target
+    if p.suffix=='.ipynb': p = nbpath2html(p)
+    elif p.suffix=='.qmd': p = p.with_suffix('.html')
+    path = urljoin(nbdir.rstrip('/')+'/', p.as_posix()).lstrip('/')
+    return urljoin(base.rstrip('/')+'/', urlunsplit(('', '', path, u.query, u.fragment)))
+
+
+def rewrite_links(node, base, nbdir='.'):
+    "Rewrite documentation links in a Pandoc syntax tree."
+    if isinstance(node, list):
+        for item in node: rewrite_links(item, base, nbdir)
+    elif isinstance(node, dict):
+        if node.get('t')=='Link': node['c'][2][0] = doc_link(node['c'][2][0], base, nbdir)
+        for item in node.values(): rewrite_links(item, base, nbdir)
+
+
+@call_parse
+def main(
+    fmt:str, # Output format supplied by Pandoc
+):
+    "Rewrite documentation links in Pandoc JSON from stdin."
+    cfg,doc = get_config(),loads(sys.stdin.read())
+    rewrite_links(doc['blocks'], cfg.doc_url, Path(cfg.readme_nb).parent.as_posix())
+    print(dumps(doc))

{nbdev-3.3.24 → nbdev-3.3.26}/nbdev/release.py

@@ -5,9 +5,10 @@ Docs: https://nbdev.fast.ai/api/release.html.md"""
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/18_release.ipynb.
 
 # %% auto #0
-__all__ = ['GH_HOST', 'CONDA_WARNING', 'update_changelog', 'Release', 'changelog', 'push_release', 'release_git', 'release_gh',
-           'pypi_json', 'latest_pypi', 'pypi_details', 'conda_output_path', 'write_conda_meta', 'write_requirements',
-           'anaconda_upload', 'release_conda', 'chk_conda_rel', 'release_pypi', 'release_both', 'nbdev_bump_version']
+__all__ = ['GH_HOST', 'CHANGELOG_MARKER', 'CHANGELOG_TMPL', 'CONDA_WARNING', 'update_changelog', 'Release', 'changelog',
+           'push_release', 'release_git', 'release_gh', 'pypi_json', 'latest_pypi', 'pypi_details', 'conda_output_path',
+           'write_conda_meta', 'write_requirements', 'anaconda_upload', 'release_conda', 'chk_conda_rel',
+           'release_pypi', 'release_both', 'nbdev_bump_version']
 
 # %% ../nbs/api/18_release.ipynb #c35cc2b8
 from fastcore.all import *
@@ -15,7 +16,7 @@ from ghapi.core import *
 
 from datetime import datetime
 from packaging.version import Version
-import shutil,subprocess,asyncio
+import subprocess,asyncio
 
 from .doclinks import *
 
@@ -60,8 +61,12 @@ def _release_head():
     return head
 
 # %% ../nbs/api/18_release.ipynb #dcaba486
-def update_changelog(txt, ver, notes, marker='<!-- do not remove -->\n'):
+CHANGELOG_MARKER = '<!-- do not remove -->\n'
+CHANGELOG_TMPL = f'# Release notes\n\n{CHANGELOG_MARKER}'
+
+def update_changelog(txt, ver, notes, marker=CHANGELOG_MARKER):
     "Insert `notes` into changelog `txt` after `marker`, replacing any existing section for `ver`"
+    if marker not in txt: raise ValueError(f"The changelog has no {marker.strip()!r} marker: add it near the top")
     txt = re.sub(rf'\n## {re.escape(ver)}\n.*?(?=\n## |\Z)', '', txt, flags=re.S)
     return txt.replace(marker, marker+notes.rstrip('\n')+'\n\n').rstrip('\n')+'\n'
 
@@ -86,7 +91,7 @@ class Release:
         self.groups = groups
 
     async def _issues(self, label):
-        return await self.gh.issues.list_for_repo(state='closed', sort='created', filter='all', since=self.commit_date, labels=label)
+        return await self.gh.issues.list_for_repo(state='closed', sort='created', since=self.commit_date, labels=label)
     async def _issue_groups(self): return await asyncio.gather(*map(self._issues, self.groups.keys()))
 
 # %% ../nbs/api/18_release.ipynb #aa22dfe3
@@ -94,8 +99,7 @@ class Release:
 async def changelog(self:Release,
               debug=False): # Just print the latest changes, instead of updating file
     "Create the CHANGELOG.md file, or return the proposed text if `debug` is `True`"
-    if not self.changefile.exists(): self.changefile.write_text("# Release notes\n\n<!-- do not remove -->\n")
-    marker = '<!-- do not remove -->\n'
+    if not self.changefile.exists(): self.changefile.write_text(CHANGELOG_TMPL, encoding='utf-8')
     try: self.commit_date = (lr:=await self.gh.repos.get_latest_release()).published_at
     except APIError as e:
         if e.status_code != 404: raise
@@ -111,9 +115,8 @@ async def changelog(self:Release,
     sections = (_issues_txt(*o) for o in zip(issues, self.groups.values()))
     res += '\n\n'.join(filter(None, sections))
     if debug: return res
-    res = update_changelog(self.changefile.read_text(), self.cfg.version, res, marker)
-    shutil.copy(self.changefile, self.changefile.with_suffix(".bak"))
-    self.changefile.write_text(res)
+    res = update_changelog(self.changefile.read_text(encoding='utf-8'), self.cfg.version, res)
+    self.changefile.write_text(res, encoding='utf-8')
     run(f'git add {self.changefile}')
 
 # %% ../nbs/api/18_release.ipynb #068421c6
@@ -132,8 +135,8 @@ async def release(self:Release):
 def latest_notes(self:Release):
     "Latest CHANGELOG entry"
     if not self.changefile.exists(): return ''
-    its = re.split(r'^## ', self.changefile.read_text(), flags=re.MULTILINE)
-    if not len(its)>0: return ''
+    its = re.split(r'^## ', self.changefile.read_text(encoding='utf-8'), flags=re.MULTILINE)
+    if len(its) < 2: return ''
     return '\n'.join(its[1].splitlines()[1:]).strip()
 
 # %% ../nbs/api/18_release.ipynb #01cb1ca4

nbdev-3.3.26/nbdev/skill.py

@@ -0,0 +1,63 @@
+"""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 and reading
+
+Published-library notebooks: interleave implementation, explanation, examples, outputs and failure demonstrations for top-to-bottom reading. Internal projects: match surrounding notebooks.
+
+Check each file, not the repo: `# AUTOGENERATED! DO NOT EDIT!` names the source notebook; `# %% ../nbs/04_usage.ipynb #a45f753a` identifies its source cell. Edit that notebook, never generated modules, `__all__`, `_modidx.py`, or module docstrings; `nbdev-export` regenerates them. Unmarked modules are hand-written. Understand and review work through notebooks and their `git diff`, never generated modules: those lack prose, examples and tests.
+
+Use notebooks to teach APIs through narrative/examples, plain `.py` for dense mechanism iterated under pytest (rarely; never add pytests to a project without them unless asked). Lessons test notebook code; `tests/*.py` test plain modules. For project-level questions, read `nbs/index.ipynb` (README.md's source); regenerate with `nbdev-readme` after changes.
+
+## Authoring
+
+Before notebook edits, 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. Choose tutorial, how-to, explanation, or reference. Open with an H1 title cell, `>` subtitle and brief introduction. Use H2s for major concepts without fragmenting short narratives; each heading gets its own markdown cell for Jupyter collapse.
+
+Develop one idea at a time: small implementation, explanation, lesson for every substantive API. Basic functionality outside the API, with little logic, generally needs no lesson. Introduce lessons in markdown; split when the introduction becomes complicated. Extend examples rather than adding near-duplicates. Build classes with `@patch` beside each method's explanation unless that obscures the API.
+
+When new behavior needs teaching (often unnecessary for trivial logic), choose its narrative position, write the lesson first (better, slightly modify an existing lesson), run preceding cells as needed, see it fail. Add its markdown introduction and implementation above it; 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. No documented behavior change: change no lesson cells. Never add a cell merely to witness a fix.
+
+Read existing examples before experimenting. Explore in the notebook, not a separate kernel check; keep useful explorations as lessons, delete the rest. Always try to leave the notebook better. Reserve underscore names for machinery without a coherent independent contract, not everything used internally. A helper useful only internally often signals awkward design.
+
+## Lessons
+
+Readability comes first: guide readers through what code does using code and displayed output. If a displayed value is worth testing, assign, test, then show it. Test the point of the code, not incidentals such as formatting. Show errors only when readers are likely to hit them.
+
+Use realistic values, minimal setup, reused objects and direct supporting assertions. Show evidence with compact `_repr_markdown_`, 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.
+
+Test-serving cells don't belong on the page: signs include safety-only setup and glue checks. Usually remove them; move substantive logic checks to `#| hide` or pytest. Discuss such changes carefully. Keep plumbing, mocks, dense comprehensions and long setup out of reader-facing examples: extract a small helper or hide the check.
+
+Consider these rewrites:
+- Commented examples -> prose/code; numbered steps -> markdown/code pairs. Keep comments stating constraints code cannot show.
+- Sentence-wrapped `print` -> prose/displayed value; final `print(x)` -> bare `x`.
+- Reassignment stages and blank-line groups -> separate cells, each introduced.
+- Near-duplicates: explain the differing argument; don't repeat setup.
+- Errors: `expect_fail`, not `try`/`except`. Long docstrings -> markdown.
+- Resolve TODO/FIXME example comments or move them to issues.
+
+## Prose and exports
+
+In markdown, explain rationale, distinctions and guarantees, not code line-by-line or filler transitions. Place it for correct generated-page reading, normally after definitions. Use short symbol docstrings, parameter/return docments beside signatures and backticked symbols for nbdev links. Extended explanation, examples and warnings belong in markdown.
+
+`nbdev-export` assembles module docstrings from the title's `>` description and exported markdown after H1; use one exported markdown cell per major section for long docstrings. `doc(module)` lists functions; in module prose, explain only shared constraints/workflows.
+
+`#| exportd` includes a code cell as fenced docstring source, not module code. Use compact runnable demos after required definitions; end the preceding exported summary with a colon. Intervening unexported definitions don't appear in the docstring. Check claims by running code before documenting; preview assembly with `nbdev.export.nb_mdoc`. A docstring beyond the default summary makes `nbdev-export` list the module in package docs and `llms.txt`. Only extend docstrings of modules read independently. Export `index.ipynb`'s opening paragraphs for the package intro.
+
+## State and execution
+
+Define values near first use, introduce shared setup, reuse established objects; don't reassign names later cells depend on. End explorations with the expression recording what was learned when useful. Keep imports in dedicated cells, lessons included: docs builds execute import-containing cells in fresh namespaces; mixed state-dependent code can fail or run at documentation time.
+
+Outputs are generated and may be stale during edits. Don't stop work, clear them manually, or edit notebook JSON because of source/output mismatch. At PR time, regenerate with `nbdev-test --save` if the project keeps saved outputs. `nbdev-test --file-re` runs several named notebooks in parallel.
+
+## 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`: code that must not run, not broken code. Later cells can't use its state.
+- Metadata directives work too: `{"nbdev": {"export": "true"}}`; `fastcore.nbio.mk_cell(...).directives` merges both forms, content winning conflicts.
+
+nbdev v3 (Jan 2026): `pyproject.toml`, not `settings.ini`; metadata in `[project]`, settings in `[tool.nbdev]` (defaults `nbs_path='nbs'`, `doc_path='_docs'`), version in `__init__.py` via `dynamic = ["version"]`, `_modidx` in `[project.entry-points.nbdev]`. CLIs use hyphens (`nbdev-export`, `nbdev-test`); Python names retain underscores. GitHub actions: `fastai/workflows/nbdev3-ci`, `quarto-ghp3`.
+
+## Finish
+
+Revise affected prose, displays and assertions together; changed assertions must fail on old code and pass on new. Re-read touched narrative for readability. Run `nbdev-test <nb>`.
+"""

{nbdev-3.3.24 → nbdev-3.3.26/nbdev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.24
+Version: 3.3.26
 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.24 → nbdev-3.3.26}/nbdev.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ nbdev/processors.py
 nbdev/qmd.py
 nbdev/quarto.py
 nbdev/quarto_render.py
+nbdev/readme_filter.py
 nbdev/release.py
 nbdev/scrubmagics.py
 nbdev/serve.py

nbdev-3.3.26/tests/test_quarto_render.py

@@ -0,0 +1,94 @@
+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, quarto_stale
+from nbdev.quarto import nbdev_readme, refresh_quarto_yml
+from nbdev.readme_filter import doc_link
+from fastcore.nbio import new_nb, mk_cell, write_nb
+
+
+@pytest.mark.skipif(not shutil.which('quarto'), reason='requires Quarto')
+def test_readme_links(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path/'pyproject.toml').write_text(r'''[project]
+name = "example"
+[project.urls]
+Documentation = "https://example.com/project/"
+[tool.nbdev]
+''')
+    nbs = tmp_path/'nbs'
+    nbs.mkdir()
+    base = 'https://example.com/project/'
+    links = [('guide/01_Intro.ipynb?q=1#intro', base+'guide/intro.html?q=1#intro'),
+        ('guide/02_intro.qmd', base+'guide/02_intro.html'), ('guide/intro.html', base+'guide/intro.html'),
+        ('/llms.txt', base+'llms.txt'), ('llms-ctx.txt', base+'llms-ctx.txt'),
+        ('https://other.com/guide.html', 'https://other.com/guide.html'),
+        ('#section', '#section'), ('LICENSE', 'LICENSE')]
+    text = '\n\n'.join([*(f'[Link]({src})' for src,_ in links),
+        r'[Reference][guide] ![Image](image.png)', r'[guide]: guide/01_Intro.ipynb#intro',
+        '```markdown\n[Example](guide/01_Intro.ipynb)\n```'])
+    write_nb(new_nb([mk_cell('# Example', 'markdown'), mk_cell(text, 'markdown')]), nbs/'index.ipynb')
+    refresh_quarto_yml()
+    nbdev_readme.__wrapped__()
+    result = (tmp_path/'README.md').read_text()
+    for _,dest in links: assert f']({dest})' in result
+    assert f'[Reference]({base}guide/intro.html#intro)' in result
+    assert '![Image](image.png)' in result and '[Example](guide/01_Intro.ipynb)' in result
+    teq(doc_link('../guide/01_intro.ipynb', base, 'start'), base+'guide/intro.html')
+    teq(doc_link('/llms.txt', base, 'start'), base+'llms.txt')
+    teq(doc_link('//other.com/llms.txt', base), '//other.com/llms.txt')
+
+
+@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')
+    (root/'other.qmd').write_text('---\noutput-file: renamed.html\n---\n# Other')
+    serial, parallel = tmp_path/'serial', root/'_site'
+    assert quarto_stale(root, parallel)
+    render_quarto(root, serial, n_workers=1)
+    render_quarto(root, parallel, n_workers=2)
+    assert not quarto_stale(root, parallel)
+    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)), 4)
+    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.')
+    assert quarto_stale(root, parallel)
+    subprocess.run(['quarto', 'render', 'beta.qmd', '--quiet', '--output-dir', str(parallel)], cwd=root, check=True)
+    assert not quarto_stale(root, parallel)
+    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.24/nbdev/skill.py

@@ -1,82 +0,0 @@
-"""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.24/tests/test_quarto_render.py

@@ -1,54 +0,0 @@
-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']