nbdev 3.3.23__tar.gz → 3.3.25__tar.gz

{nbdev-3.3.23/nbdev.egg-info → nbdev-3.3.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.23
+Version: 3.3.25
 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.23 → nbdev-3.3.25}/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.23"
+__version__ = "3.3.25"
 
 from .doclinks import nbdev_export
 from .showdoc import show_doc

{nbdev-3.3.23 → nbdev-3.3.25}/nbdev/config.py

@@ -360,7 +360,7 @@ def add_init(path=None):
         subds = (os.listdir(r/d) for d in ds)
         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)
+    if get_config().get('update_pyproject', True): update_proj(get_config().config_path)
     update_init_mdoc(path)
 
 # %% ../nbs/api/01_config.ipynb #a01b98bb

{nbdev-3.3.23 → nbdev-3.3.25}/nbdev/quarto.py

@@ -63,8 +63,8 @@ def install_quarto():
 def install():
     "Install Quarto and the current library"
     install_quarto.__wrapped__()
-    d = get_config().lib_path
-    if (d/'__init__.py').exists(): system(f'pip install -e "{d.parent}[dev]"')
+    cfg = get_config()
+    if (cfg.lib_path/'__init__.py').exists(): system(f'pip install -e "{cfg.config_path}[dev]"')
 
 # %% ../nbs/api/14_quarto.ipynb #b93f6def
 def _pre(p,b=True): return '    ' * (len(p.parts)) + ('- ' if b else '  ')
@@ -201,7 +201,7 @@ def refresh_quarto_yml():
 def _ensure_quarto():
     if shutil.which('quarto'): return
     print("Quarto is not installed. We will download and install it for you.")
-    install.__wrapped__()
+    install_quarto.__wrapped__()
 
 # %% ../nbs/api/14_quarto.ipynb #66163c30
 def _chk_nbdev_yml(path):
@@ -290,7 +290,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)
 

nbdev-3.3.25/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.23 → nbdev-3.3.25}/nbdev/release.py

@@ -260,7 +260,7 @@ def _get_conda_meta():
         'source': {'url':rel['url'], 'sha256':rel['digests']['sha256']}
     }
 
-    _dir = cfg.lib_path.parent
+    _dir = cfg.config_path
     readme = _dir/'README.md'
     descr = readme.read_text() if readme.exists() else ''
     d2 = {
@@ -360,7 +360,7 @@ def release_pypi(
     verbose:bool=False # Pass --verbose to twine upload
 ):
     "Create and upload Python package to PyPI"
-    _dir = get_config().lib_path.parent
+    _dir = get_config().config_path
     q = ' --quiet' if quiet else ''
     p = ' --disable-progress-bar' if quiet else ''
     system(f'cd {_dir}  && rm -rf dist build && python -m build{q}')

{nbdev-3.3.23 → nbdev-3.3.25}/nbdev/skill.py

@@ -1,6 +1,6 @@
 """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
+## 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.
 
@@ -10,7 +10,7 @@ Understand and review work through the notebooks and their `git diff`, never gen
 
 For project-level questions, read `nbs/index.ipynb`, the source of README.md; regenerate with `nbdev-readme` after changes.
 
-# Structure and authoring
+## 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.
 
@@ -18,13 +18,13 @@ Before changing a notebook, read the whole notebook or a summary of every cell.
 
 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.
+When new behavior needs a lesson (which it often doesn't, if it's trivial logic that doesn't need teaching), choose its narrative position, write the lesson first (or better still, slightly modify and existing listen), 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
+## 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.
 
@@ -34,7 +34,7 @@ In markdown, explain rationale, distinctions and guarantees. Don't narrate code
 
 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
+## Lesson cells
 
 A notebook guides a reader through what the code does. Readability comes first.
 
@@ -59,7 +59,7 @@ Consider a rewrite when you see these:
 - 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
+## 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.
 
@@ -67,7 +67,7 @@ Keep imports in dedicated cells, including in lessons: docs builds execute impor
 
 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
+## 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.
@@ -76,7 +76,7 @@ Stored outputs are generated and may be stale during editing. Don't stop work, c
 
 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
+## 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.23 → nbdev-3.3.25/nbdev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.23
+Version: 3.3.25
 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.23 → nbdev-3.3.25}/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.23 → nbdev-3.3.25}/tests/test_quarto_render.py

@@ -2,6 +2,41 @@ 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
+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')