nbdev 3.3.3__tar.gz → 3.3.5__tar.gz

{nbdev-3.3.3/nbdev.egg-info → nbdev-3.3.5}/PKG-INFO

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

{nbdev-3.3.3 → nbdev-3.3.5}/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.3"
+__version__ = "3.3.5"
 
 from .doclinks import nbdev_export
 from .showdoc import show_doc

{nbdev-3.3.3 → nbdev-3.3.5}/nbdev/_modidx.py

@@ -210,6 +210,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.5/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.3 → nbdev-3.3.5}/nbdev/quarto.py

@@ -208,8 +208,10 @@ def _chk_nbdev_yml(path):
 
 # %% ../nbs/api/14_quarto.ipynb #6b880922
 def _pre_docs(path=None, n_workers:int=defaults.cpus, **kwargs):
-    cfg = get_config()
-    path = Path(path) if path else cfg.nbs_path
+    cfg = get_config(path)
+    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()
@@ -272,12 +274,14 @@ def _save_cached_readme(cache, cfg):
 # %% ../nbs/api/14_quarto.ipynb #45d6bb5d
 @call_parse
 def nbdev_readme(
-    path:str=None, # Path to notebooks
+    path:str=None, # Path to notebooks (or project root)
     chk_time:bool=False): # Only build if out of date
     "Create README.md from readme_nb (index.ipynb by default). Skips if the file doesn't exist."
-    cfg = get_config()
-    path = Path(path) if path else cfg.nbs_path
+    cfg = get_config(path)
+    path = Path(path).absolute() if path else cfg.nbs_path
+    if not (path/cfg.readme_nb).exists(): path = cfg.nbs_path  # given a project root, fall back to its configured nbs
     if not (path/cfg.readme_nb).exists(): return
+    os.chdir(cfg.config_path)  # bare `get_config()` runs downstream (including in render workers), so anchor the cwd
     _chk_nbdev_yml(path)
     if chk_time and _doc_mtime_not_older(cfg.config_path/'README.md', path/cfg.readme_nb): return
 

{nbdev-3.3.3 → nbdev-3.3.5}/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.3 → nbdev-3.3.5}/nbdev/serve.py

@@ -70,7 +70,7 @@ def proc_nbs(
     file_re:str='', # Only process notebooks matching regex (other files are always included)
     **kwargs):
     "Process notebooks in `path` for docs rendering"
-    cfg = get_config()
+    cfg = get_config(path or None)
     cache = cfg.config_path/'_proc'
     path = Path(path or cfg.nbs_path)
     files = nbglob(path, func=Path, file_glob='', file_re='', **kwargs)

{nbdev-3.3.3 → nbdev-3.3.5}/nbdev/skill.py

@@ -72,6 +72,8 @@ Keep imports in dedicated import cells, define values near first use, reuse esta
 
 Everything here describes nbdev v3 (released Jan 2026, possibly after a model's training cutoff). Key user-visible changes from v2: config moved from `settings.ini` to `pyproject.toml`, with standard metadata in `[project]`, nbdev-specific keys in `[tool.nbdev]` (defaults `nbs_path='nbs'`, `doc_path='_docs'`), version in `__init__.py` via `dynamic = ["version"]`, and `_modidx` registered under `[project.entry-points.nbdev]`. CLI commands use hyphens (`nbdev-export`, `nbdev-test`, ...) though Python functions keep underscores. GitHub workflows use the v3 actions (`fastai/workflows/nbdev3-ci`, `quarto-ghp3`).
 
+Directives can also live in cell *metadata*, under the `nbdev` key (`{"nbdev": {"export": "true"}}`), instead of `#|` comment lines. Export and the rest of the toolchain honor both; `mk_cell(source, metadata=...).directives` is the merged read, with the comment winning when both set the same key. The editing toolkit keeps the meta form visible: summaries show it bracketed after the type char (`id:c[export]:...` in nbio's `CellRow` and aidialog's previews), XML views render it as attrs (a bare `export` on the tag), and aidialog's `Message` offers `exported` (either form, read-only) and `meta_exported` (meta only, assignable), with `export=`/`meta=` params on the add functions.
+
 # Before you finish
 
 Each new test cell ran red then green, failing before the change and passing after. Re-read the touched section as a reader would, against the conventions above. Style damage breaks no test and no export, so the harm only shows on the docs page.

{nbdev-3.3.3 → nbdev-3.3.5/nbdev.egg-info}/PKG-INFO

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

{nbdev-3.3.3 → nbdev-3.3.5}/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