nbdev 3.3.4__tar.gz → 3.3.6__tar.gz

{nbdev-3.3.4/nbdev.egg-info → nbdev-3.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.4
+Version: 3.3.6
 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.11
+Requires-Dist: fastcore>=2.2.3
 Requires-Dist: execnb>=0.2.8
 Requires-Dist: astunparse
 Requires-Dist: ghapi>=2.0.2

{nbdev-3.3.4 → nbdev-3.3.6}/nbdev/__init__.py

@@ -3,9 +3,10 @@
 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 clear, executable nbdev notebooks where code, prose, examples, outputs, and tests form one coherent narrative."""
 
-__version__ = "3.3.4"
+__version__ = "3.3.6"
 
 from .doclinks import nbdev_export
 from .showdoc import show_doc

{nbdev-3.3.4 → nbdev-3.3.6}/nbdev/_modidx.py

@@ -141,10 +141,8 @@ d = { 'settings': { 'branch': 'main',
                                    'nbdev.frontmatter.FrontmatterProc.end': ( 'api/frontmatter.html#frontmatterproc.end',
                                                                               'nbdev/frontmatter.py'),
                                    'nbdev.frontmatter._dict2fm': ('api/frontmatter.html#_dict2fm', 'nbdev/frontmatter.py'),
-                                   'nbdev.frontmatter._fm2dict': ('api/frontmatter.html#_fm2dict', 'nbdev/frontmatter.py'),
-                                   'nbdev.frontmatter._insertfm': ('api/frontmatter.html#_insertfm', 'nbdev/frontmatter.py'),
-                                   'nbdev.frontmatter._md2dict': ('api/frontmatter.html#_md2dict', 'nbdev/frontmatter.py'),
-                                   'nbdev.frontmatter.nb_frontmatter': ('api/frontmatter.html#nb_frontmatter', 'nbdev/frontmatter.py')},
+                                   'nbdev.frontmatter._fm2dict_md': ('api/frontmatter.html#_fm2dict_md', 'nbdev/frontmatter.py'),
+                                   'nbdev.frontmatter._insertfm': ('api/frontmatter.html#_insertfm', 'nbdev/frontmatter.py')},
             'nbdev.imports': {},
             'nbdev.maker': { 'nbdev.maker.ModuleMaker': ('api/maker.html#modulemaker', 'nbdev/maker.py'),
                              'nbdev.maker.ModuleMaker.__init__': ('api/maker.html#modulemaker.__init__', 'nbdev/maker.py'),
@@ -210,6 +208,7 @@ d = { 'settings': { 'branch': 'main',
                                'nbdev.migrate.migrate_nb': ('api/migrate.html#migrate_nb', 'nbdev/migrate.py'),
                                'nbdev.migrate.nbdev_migrate': ('api/migrate.html#nbdev_migrate', 'nbdev/migrate.py'),
                                'nbdev.migrate.nbdev_migrate_config': ('api/migrate.html#nbdev_migrate_config', 'nbdev/migrate.py')},
+            'nbdev.moddocs': {},
             'nbdev.process': { 'nbdev.process.NBProcessor': ('api/process.html#nbprocessor', 'nbdev/process.py'),
                                'nbdev.process.NBProcessor.__init__': ('api/process.html#nbprocessor.__init__', 'nbdev/process.py'),
                                'nbdev.process.NBProcessor._proc': ('api/process.html#nbprocessor._proc', 'nbdev/process.py'),

{nbdev-3.3.4 → nbdev-3.3.6}/nbdev/frontmatter.py

@@ -5,7 +5,7 @@ Docs: https://nbdev.fast.ai/api/frontmatter.html.md"""
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/09_frontmatter.ipynb.
 
 # %% auto #0
-__all__ = ['nb_frontmatter', 'FrontmatterProc']
+__all__ = ['FrontmatterProc']
 
 # %% ../nbs/api/09_frontmatter.ipynb #2398f5ef-06d3-4890-8a54-7cf4f81f3894
 from .imports import *
@@ -21,38 +21,15 @@ _RE_FM_BASE=r'''^---\s*
 (.*?\S+.*?)
 ---\s*'''
 
-_re_fm_nb = re.compile(_RE_FM_BASE+'$', flags=re.DOTALL)
 _re_fm_md = re.compile(_RE_FM_BASE, flags=re.DOTALL)
 
+
 # %% ../nbs/api/09_frontmatter.ipynb #1725f3b9
-def _fm2dict(s:str, nb=True):
-    "Load YAML frontmatter into a `dict`"
-    re_fm = _re_fm_nb if nb else _re_fm_md
-    match = re_fm.search(s.strip())
+def _fm2dict_md(s:str):
+    "Load YAML frontmatter opening a markdown file (body allowed) into a `dict`"
+    match = _re_fm_md.search(s.strip())
     return yaml.safe_load(match.group(1)) if match else {}
 
-def _md2dict(s:str):
-    "Convert H1 formatted markdown cell to frontmatter dict"
-    if '#' not in s: return {}
-    m = re.search(r'^#\s+(\S.*?)\s*$', s, flags=re.MULTILINE)
-    if not m: return {}
-    res = {'title': m.group(1)}
-    m = re.search(r'^>\s+(\S.*?)\s*$', s, flags=re.MULTILINE)
-    if m: res['description'] = m.group(1)
-    r = re.findall(r'^-\s+(\S.*:.*\S)\s*$', s, flags=re.MULTILINE)
-    if r:
-        try: res.update(yaml.safe_load('\n'.join(r)))
-        except Exception as e: warn(f'Failed to create YAML dict for:\n{r}\n\n{e}\n')
-    return res
-
-# %% ../nbs/api/09_frontmatter.ipynb #4ba11b21
-def nb_frontmatter(nb):
-    "Get frontmatter dict from `nb` without modifying cells"
-    raw = first(c for c in nb.cells if c.cell_type=='raw')
-    md  = first(c for c in nb.cells if c.cell_type=='markdown')
-    res = _md2dict(md.source) if md else {}
-    if raw: res.update(_fm2dict(raw.source))
-    return res
 
 # %% ../nbs/api/09_frontmatter.ipynb #1b5d9d32
 def _dict2fm(d): return f'---\n{yaml.dump(d)}\n---\n\n'
@@ -71,8 +48,8 @@ class FrontmatterProc(Processor):
         cell.source = None
 
     def cell(self, cell):
-        if cell.cell_type=='raw': self._update(_fm2dict, cell)
-        elif cell.cell_type=='markdown' and 'title' not in self.fm: self._update(_md2dict, cell)
+        if cell.cell_type=='raw': self._update(cell_frontmatter, cell)
+        elif cell.cell_type=='markdown' and 'title' not in self.fm: self._update(md_frontmatter, cell)
 
     def end(self):
         self.nb.frontmatter_ = self.fm

{nbdev-3.3.4 → nbdev-3.3.6}/nbdev/migrate.py

@@ -11,7 +11,7 @@ __all__ = ['MigrateProc', 'fp_md_fm', 'migrate_nb', 'migrate_md', 'nbdev_migrate
 from .process import *
 from fastcore.nbio import first_code_ln, langs
 from .frontmatter import *
-from .frontmatter import _fm2dict, _re_fm_md, _dict2fm, _insertfm
+from .frontmatter import _fm2dict_md, _re_fm_md, _dict2fm, _insertfm
 from .processors import *
 from .config import get_config, read_nb, set_version, pyproject_tmpl, nbdev_defaults
 from .sync import write_nb
@@ -98,7 +98,7 @@ def fp_md_fm(path):
     "Make fastpages front matter in markdown files quarto compliant."
     p = Path(path)
     md = p.read_text()
-    fm = _fm2dict(md, nb=False)
+    fm = _fm2dict_md(md)
     if fm:
         fm = _fp_convert(fm, path)
         return _re_fm_md.sub(_dict2fm(fm), md)

nbdev-3.3.6/nbdev/moddocs.py

@@ -0,0 +1,84 @@
+r"""# Module docs: creating them from existing notebooks
+
+Module docs are the LLM-facing documentation channel of an nbdev project: module docstrings, the package docstring, and `llms.txt`, all generated by `nbdev-export`. They ship inside the code, so they are there for every user of the library with no separate network lookup, and they cannot be stale relative to the installed version. They also make learning uniform. One call, `doc(foo)`, teaches a package, a module, a class, or a function, and plain `help(foo)` shows the same text. A reader works progressively: `llms.txt` or the package docstring says which modules matter, `doc(module)` teaches one module in a single read, and the `Docs:` URL ending each docstring leads to the full page when needed.
+
+This guide covers one task. A project's notebooks already exist, and you are creating the module docs from them. General notebook authoring, and the `#| export`/`#| exportd` docstring mechanics, are `doc(nbdev.skill)`'s job. Read it first.
+
+## Creating a module's docs from its notebook
+
+The notebook already contains the documentation. Its author made the content decisions when writing it: which ideas get prose, which examples demonstrate them, what matters. Creating module docs is a projection of that material, not new writing. The work is deciding which prose becomes the docstring, and reshaping it to stand alone.
+
+Start with the baseline. Run `doc(module)` as-is and note what a reader gets today, usually the bare summary line. Then read the whole notebook, sorting its markdown into two kinds:
+
+- Standalone prose, which teaches a concept without depending on the cells around it. These are tagging candidates.
+- Cell-adjacent prose ("...to this:", "The code for `Int` is shown below:", six cells walking one function's variations). These cannot export as-is.
+
+The mix decides between two options, and the user picks:
+
+**Option 1: extract.** Build the docstring from the notebook's own narrative. When a cell stands alone, tag it `#| export` where it sits. When it nearly stands alone, reshape lightly first:
+
+- Split the cell so only the standalone part is tagged.
+- End a summary with a colon so it reads straight into a `#| exportd` demo.
+- Fix wording that only works on the page, such as "the helpers below" or "as shown above".
+
+Where a section's prose is all cell-adjacent, write one new summary cell under its heading, condensing what those cells teach: the idioms a reader could not guess from signatures, with the long tail left to the docs page. This improves the docs page at the same time, since a section that jumped straight into per-function detail was missing its overview anyway. When most of a module's docs can be tagged nearly as-is, the original notebook was authored well, and the docstring comes almost for free.
+
+**Option 2: front block.** Write the docstring as a few fresh markdown cells right after the title, optionally with `#| exportd` demos between them, all tagged, forming one self-contained overview read top to bottom. Reach for this when extraction keeps producing fragments, when the notebook's structure doesn't match the story the docstring should tell, or when the user simply prefers it. It is the simplest safe default. Nothing the author wrote is touched, so nothing on the page changes, except that the page gains an overview at the top, which usually helps. Don't push for restructuring the whole notebook when a front block serves.
+
+**Demos.** An existing example cell can often be tagged `#| exportd` as-is. A new demo must run after the definitions it uses, so its notebook position is constrained, but its docstring position is not. Only tagged cells assemble, so a summary and its demo sit adjacent in the docstring however many definition cells separate them in the notebook. Run every demo in notebook order and see it pass. Run code to check every prose claim too, since old prose can be stale, and a docstring stating something false is worse than one stating nothing.
+
+**Iterate and review.** Preview with `nbdev.export.nb_mdoc(nbname)`, which shows the docstring the notebook would produce, until it reads well top to bottom. Then show the user every new and changed cell verbatim, as markdown and code with their directives. Cell ids and diffs are not reviewable. The actual text is. After export, read `doc(module)` the way the eventual reader will.
+
+## Creating the package docs from index.ipynb
+
+The same projection applies at package level. `index.ipynb` already carries the project intro, and tagging markdown there feeds both the package docstring (written into `__init__.py`) and `llms.txt`. The pieces:
+
+- The summary line is `[project].description` from `pyproject.toml`.
+- Tag the intro paragraphs `#| export`. Tips lists, curated links, and a short `#| exportd` quick-start demo all project well. Installation instructions and marketing positioning stay untagged.
+- The `Modules:` list assembles itself: every module whose docstring now says more than the default summary-plus-link is listed with its summary line. Finishing a module's docs is what lists it, so do the modules first and the package list follows.
+- `llms.txt` is the same parts in llms.txt shape, written into `nbs/` on export.
+
+## Ask the user
+
+- Which modules get docs at all, before starting. Internal, vendored, and niche modules can stay bare, which also keeps them out of the package listing. Leaving a module bare is itself a curation decision.
+- The cut for each module, before writing: propose a summary paragraph and demo for the defining idioms, a sentence naming the supporting functions, and nothing for the rest, then wait for a steer.
+- Whether existing page prose may be rewritten in place, since that changes the docs site too.
+- Extract or front block. Present the choice with your read of how well the existing prose extracts, and let the user pick.
+- Exact-output assertions in demos, when an exact string arguably is the contract, such as a rendered template or a signature.
+- Anything discovered along the way. Report and propose stale claims in old prose, candidate deprecations, and missing features, and let the user decide. API changes are never part of a docs pass.
+
+## Worked example: fastcore.script
+
+`fastcore/nbs/06_script.ipynb` opens with a bare title cell, then a tagged overview whose first line becomes the module summary:
+
+    # Script - CLI
+
+    [cell] #| export
+    Creates a CLI from a Python function decorated with `call_parse`.
+
+    The function's parameters become the script's arguments, its docstring becomes the program description, and its [docments](https://fastcore.fast.ai/docments.html) comments become the help for each argument.
+
+Deeper in the notebook, after `is_cli` is defined, an existing summary and demo pair was tagged where it stood:
+
+    [cell] #| export
+    A function usable both from the command line and from Python can call `is_cli` to tell which way it was invoked, e.g. returning a value to Python callers but printing it (or exiting with an error code) when run as a CLI:
+
+    [cell] #| exportd
+    @call_parse
+    def sum_args(a:int=0, b:int=0):
+        "Add `a` and `b`"
+        if is_cli(): print(a+b)
+        else: return a+b
+
+    test_eq(sum_args(1,2), 3)  # Python call: returns the value, prints nothing
+
+In the assembled docstring the pair renders as the summary followed by a fenced python block, and the package artifacts pick the module up automatically. Its line in fastcore's `llms.txt`:
+
+    - [fastcore.script](https://fastcore.fast.ai/script.html.md): Creates a CLI from a Python function decorated with `call_parse`.
+
+Points to notice:
+
+- The docstring is a small fraction of the docs page, yet answers most usage questions. That ratio is the target.
+- The overview and the `is_cli` pair were existing cells, tagged in place with light tightening.
+- The "Param types" summary in the same notebook was condensed from scattered examples into a new cell, improving the page and the docstring together.
+- The demo asserts the behavior it teaches, and its assertion runs in the notebook's test suite from then on."""

{nbdev-3.3.4 → nbdev-3.3.6}/nbdev/processors.py

@@ -18,7 +18,6 @@ from .process import *
 from .showdoc import *
 from .doclinks import *
 from .frontmatter import *
-from .frontmatter import _fm2dict
 
 from fastcore.nbio import *
 from execnb.shell import *

{nbdev-3.3.4 → nbdev-3.3.6}/nbdev/release.py

@@ -77,6 +77,7 @@ class Release:
         os.chdir(self.cfg.config_path)
         if repo and '/' in repo: owner,repo = repo.split('/', 1)
         owner,repo = owner or self.cfg.user, repo or self.cfg.repo
+        if not owner or not repo: raise Exception("Could not infer `user`/`repo` from config: add a `Repository` key under `[project.urls]` in pyproject.toml, or pass `repo='owner/repo'`")
         token = ifnone(token, os.getenv('NBDEV_TOKEN',None))
         if not token and Path('token').exists(): token = Path('token').read_text().strip()
         token = ifnone(token, os.getenv('GITHUB_TOKEN',None))
@@ -98,7 +99,7 @@ async def changelog(self:Release,
     try: self.commit_date = (lr:=await self.gh.repos.get_latest_release()).published_at
     except APIError as e:
         if e.status_code != 404: raise
-        lr,self.commit_date = None,'2000-01-01T00:00:004Z'
+        lr,self.commit_date = None,'2000-01-01T00:00:00Z'
     if lr:
         run('git fetch --tags --quiet')
         _check_changelog_base(lr.tag_name)
@@ -355,14 +356,16 @@ def chk_conda_rel(
 @call_parse
 def release_pypi(
     repository:str="pypi", # Respository to upload to (defined in ~/.pypirc)
-    quiet:bool=False # Reduce output verbosity
+    quiet:bool=False, # Reduce output verbosity
+    verbose:bool=False # Pass --verbose to twine upload
 ):
     "Create and upload Python package to PyPI"
     _dir = get_config().lib_path.parent
     q = ' --quiet' if quiet else ''
     p = ' --disable-progress-bar' if quiet else ''
     system(f'cd {_dir}  && rm -rf dist build && python -m build{q}')
-    system(f'twine upload --repository {repository}{p} {_dir}/dist/*')
+    v = ' --verbose' if verbose else ''
+    system(f'twine upload{v} --repository {repository}{p} {_dir}/dist/*')
 
 # %% ../nbs/api/18_release.ipynb #06edfcb0
 @call_parse

{nbdev-3.3.4 → nbdev-3.3.6/nbdev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.4
+Version: 3.3.6
 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.11
+Requires-Dist: fastcore>=2.2.3
 Requires-Dist: execnb>=0.2.8
 Requires-Dist: astunparse
 Requires-Dist: ghapi>=2.0.2

{nbdev-3.3.4 → nbdev-3.3.6}/nbdev.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ nbdev/imports.py
 nbdev/maker.py
 nbdev/merge.py
 nbdev/migrate.py
+nbdev/moddocs.py
 nbdev/process.py
 nbdev/processors.py
 nbdev/qmd.py

{nbdev-3.3.4 → nbdev-3.3.6}/nbdev.egg-info/requires.txt

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

{nbdev-3.3.4 → nbdev-3.3.6}/pyproject.toml

@@ -19,7 +19,7 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
 ]
 dynamic = ["version"]
-dependencies = [ "fastcore>=2.1.11", "execnb>=0.2.8", "astunparse", "ghapi>=2.0.2", "watchdog", "asttokens",
+dependencies = [ "fastcore>=2.2.3", "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]