Update docs

Author: jph00

nbs/api/01_config.ipynb

@@ -558,7 +558,11 @@
    "id": "78056483",
    "metadata": {},
    "source": [
-    "You can customize nbdev for all your projects by creating a `~/.config/nbdev/config.toml` file (or following the [XDG specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)). Any `[tool.nbdev]` key can go there, with the project's own setting winning: for example, `jupyter_hooks = false` globally disables nbdev's Jupyter hooks, and `cell_timeout = 60` gives `nbdev-test` a default cell timeout. `nbdev-create-config` also reads `user`, `author`, and `author_email` from it when neither the arguments nor the git remote supply them."
+    "Set defaults for all projects in `~/.config/nbdev/config.toml`, or its [XDG location](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). It accepts any `[tool.nbdev]` key. Project settings override these defaults.\n",
+    "\n",
+    "For example, `jupyter_hooks = false` disables the Jupyter hooks by default. `cell_timeout = 60` sets a 60-second default for `nbdev-test`.\n",
+    "\n",
+    "`nbdev-create-config` also reads `user`, `author` and `author_email` from this file when arguments and Git don't supply them."
    ]
   },
   {
@@ -904,9 +908,11 @@
    "id": "f4a02289",
    "metadata": {},
    "source": [
-    "An LLM (or person) asking `doc(pkg)` should learn which modules to read next, like a good `llms.txt`. The curation signal is the docstring itself: a module saying more than the default summary plus `Docs:` link has had documentation deliberately written for it, so it's meant to be independently useful. `pkg_mdoc` lists those modules, each with the first paragraph of its docstring, and `update_init_mdoc` writes the result as the package docstring in `__init__.py` (surgically: any code there is preserved). It runs as part of `add_init`, so plain `nbdev-export` keeps it current.\n",
+    "The package docstring helps readers of `doc(pkg)` choose which modules to read next. `pkg_mdoc` lists modules whose docstrings extend beyond the default summary and `Docs:` link. Each entry uses the module docstring's first paragraph.\n",
     "\n",
-    "Tools understand the same signal: pyskills' `doc()` treats a package with a substantive docstring as curated and elides its mechanical submodule listing, so the generated `Modules:` list is the whole answer rather than being repeated (e.g. `doc('pyskills')` itself)."
+    "`update_init_mdoc` writes this documentation into `__init__.py` without changing its code. `nbdev-export` runs it through `add_init`.\n",
+    "\n",
+    "pyskills' `doc()` uses this package documentation instead of adding its usual submodule listing. For example, see `doc('pyskills')`."
    ]
   },
   {
@@ -1004,7 +1010,9 @@
    "id": "a56dfc74",
    "metadata": {},
    "source": [
-    "The same parts also make a spec-compliant [llms.txt](https://llmstxt.org): title, `> ` summary, the index-notebook intro, and a `## Modules` section linking each substantive module to its `.html.md` page (taken from the `Docs:` line of its docstring). `update_llms_txt` writes it to the notebooks folder, where Quarto copies it to the site root. A trailing HTML-comment marker identifies the file as generated: a hand-written `llms.txt` (no marker) is never overwritten."
+    "`pkg_llms` builds an [llms.txt](https://llmstxt.org) from the same documentation. It includes the title, summary, index-notebook introduction and module list. Module links use the `.html.md` URLs from their docstrings' `Docs:` lines.\n",
+    "\n",
+    "`update_llms_txt` writes the file to the notebooks folder for Quarto to copy to the site root. It marks generated files with an HTML comment. It never overwrites an existing file without that marker."
    ]
   },
   {

nbs/api/03_process.ipynb

@@ -60,7 +60,9 @@
    "id": "cbe57d96",
    "metadata": {},
    "source": [
-    "Special comments at the start of a cell provide information to `nbdev` about how to process it. The parsing primitives live in `fastcore.nbio` (the `langs` table, `nb_lang`, `first_code_ln`, and `NbCell`'s `directives` property and `remove_directives` method) and are available here via its re-exports; this module builds the notebook processing pipeline on top of them."
+    "`NBProcessor` applies processors to notebook cells. Processors can handle every cell or respond to directives at the start of a cell.\n",
+    "\n",
+    "Directive parsing comes from `fastcore.nbio`. This module re-exports its `langs`, `nb_lang`, `first_code_ln` and `NbCell`. Cells provide the `directives` property and `remove_directives` method."
    ]
   },
   {
@@ -161,7 +163,7 @@
    "id": "85874d36",
    "metadata": {},
    "source": [
-    "Cell processors can be callables (e.g regular functions), in which case they are called for every cell (set a cell's source to `None` to remove the cell):"
+    "A callable processor runs on every cell. To remove a cell, set its source to `None`:"
    ]
   },
   {
@@ -199,15 +201,15 @@
    "id": "a8202589",
    "metadata": {},
    "source": [
-    "Directives are put in a cell attribute `directives_` as a dictionary keyed by directive name, with the raw value string as each value (`''` for a bare directive). When a processor method receives a directive, the value is whitespace-split into positional arguments:"
+    "`NBProcessor` saves each cell's directives in `directives_` before processing. This dictionary maps names to raw string values, with `''` for bare directives. Directive handlers get these values split on whitespace into positional arguments."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "8e160de8",
    "metadata": {},
    "source": [
-    "Notebook-level directives can be stored in the notebook metadata, as a dict under an `nbdev` key: they are merged into the first code cell's `directives_`, so notebook-scope directives like `default_exp` need no cell to live in. A directive of the same name anywhere in a cell takes priority."
+    "Notebook metadata can hold directives under an `nbdev` key. `NBProcessor` adds them to the first code cell's `directives_`. A directive with the same name in any cell takes precedence. For example, `default_exp` can go in notebook metadata without needing a dedicated cell:"
    ]
   },
   {
@@ -254,7 +256,7 @@
    "id": "315106a7",
    "metadata": {},
    "source": [
-    "However, a more convenient way to handle comment directives is to use a *class* as a processor, and include a method in your class with the same name as your directive, surrounded by underscores:"
+    "To handle directives in a class, name each method after its directive with surrounding underscores:"
    ]
   },
   {
@@ -283,7 +285,7 @@
    "id": "15c01642",
    "metadata": {},
    "source": [
-    "In the case that your processor supports just one comment directive, you can just use a regular function, with the same name as your directive, but with an underscore appended -- here `printme_` is identical to `_PrintExample` above:"
+    "For a single directive, a function with a trailing underscore works too. This `printme_` function does the same work as `_PrintExample`:"
    ]
   },
   {
@@ -344,7 +346,13 @@
    "id": "2fb60713",
    "metadata": {},
    "source": [
-    "For more complex behavior, inherit from `Processor`, and override one of more of `begin()` (called before any cells are processed), `cell()` (called for each cell), and `end()` (called after all cells are processed). You can also include comment directives (such as the `_printme` example above) in these subclasses. Subclasses will automatically have access to `self.nb`, containing the processed notebook."
+    "A `Processor` subclass can keep state across cells. It has access to the notebook through `self.nb`. Override these methods as needed:\n",
+    "\n",
+    "- `begin()` runs before the cells.\n",
+    "- `cell()` runs on each cell.\n",
+    "- `end()` runs after the cells.\n",
+    "\n",
+    "Subclasses can also have directive handlers such as `_printme_`."
    ]
   },
   {

nbs/api/07_merge.ipynb

@@ -67,7 +67,7 @@
    "id": "85693d12",
    "metadata": {},
    "source": [
-    "When working with jupyter notebooks (which are json files behind the scenes) and GitHub, it is very common that a merge conflict (that will add new lines in the notebook source file) will break some notebooks you are working on. This module defines the function `nbdev-fix` to fix those notebooks for you, and attempt to automatically merge standard conflicts. The remaining ones will be delimited by markdown cells like this:"
+    "Git conflict markers make notebook JSON invalid. `nbdev-fix` creates a notebook you can open in Jupyter. It resolves metadata and output conflicts automatically. For conflicting cell contents, it keeps both versions between Markdown markers:"
    ]
   },
   {
@@ -219,7 +219,7 @@
    "id": "427424b3",
    "metadata": {},
    "source": [
-    "Note that in this example, the second conflict is easily solved: it just concerns the execution count of the second cell and can be solved by choosing either option without really impacting your notebook. This is the kind of conflict we will fix automatically. The first conflict is more complicated as it spans across two cells and there is a cell present in one version, not the other. Such a conflict (and generally the ones where the inputs of the cells change form one version to the other) aren't automatically fixed, but we will return a proper json file where the annotations introduced by git will be placed in markdown cells."
+    "The second conflict affects an execution count. Either value works, so `nbdev-fix` can resolve it automatically. The first conflict spans two cells, including one missing from the other version. It needs a manual decision. `nbdev-fix` preserves both versions in a valid notebook."
    ]
   },
   {
@@ -563,9 +563,9 @@
    "id": "dd5e9a07",
    "metadata": {},
    "source": [
-    "This begins by optionally backing the notebook `fname` to `fname.bak` in case something goes wrong. Then it parses the broken json, solving conflicts in cells. Every conflict that only involves metadata or outputs of cells will be solved automatically by using the local (`theirs==False`) or the remote (`theirs==True`) branch. Otherwise, or for conflicts involving the inputs of cells, the json will be repaired by including the two version of the conflicted cell(s) with markdown cells indicating the conflicts. You will be able to open the notebook again and search for the conflicts (look for `<<<<<<<`) then fix them as you wish.\n",
+    "By default, `nbdev-fix` keeps local outputs and metadata. Pass `theirs=True` to use the other branch's values. Conflicting source remains in separate cells. Open the repaired notebook and search for `<<<<<<<` to resolve these conflicts.\n",
     "\n",
-    "A message will be printed indicating whether the notebook was fully merged or if conflicts remain."
+    "Without `outname`, the command overwrites the input notebook. Set `nobackup=False` to keep a `.ipynb.bak` copy. The completion message says whether any conflicts remain."
    ]
   },
   {
@@ -663,9 +663,9 @@
    "id": "db41a4b0",
    "metadata": {},
    "source": [
-    "This implements a [git merge driver](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver) for notebooks that automatically resolves conflicting metadata and outputs, and splits remaining conflicts as separate cells so that the notebook can be viewed and fixed in Jupyter. The easiest way to install it is by running `nbdev-install-hooks`.\n",
+    "Run `nbdev-install-hooks` to install the notebook [Git merge driver](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver). It first runs Git's standard merge, then calls `nbdev-fix` if conflicts remain.\n",
     "\n",
-    "This works by first running Git's default merge driver, and then `nbdev-fix` if there are still conflicts. You can set `nbdev-fix`'s `theirs` argument using the `THEIRS` environment variable, for example:\n",
+    "Set the `THEIRS` environment variable to choose the other branch's outputs and metadata:\n",
     "\n",
     "    THEIRS=True git merge branch"
    ]

nbs/api/11_clean.ipynb

@@ -60,7 +60,7 @@
    "id": "3c669488",
    "metadata": {},
    "source": [
-    "To avoid pointless conflicts while working with jupyter notebooks (with different execution counts or cell metadata), it is recommended to clean the notebooks before committing anything (done automatically if you install the git hooks with `nbdev-install-hooks`). The following functions are used to do that. Cleaning also adds cell `id`s if missing (required by nbformat 4.5+)."
+    "Clean notebooks before committing to remove execution counts and metadata that cause unnecessary merge conflicts. Install the hooks with `nbdev-install-hooks` to clean notebooks automatically. Cleaning also adds missing cell IDs, which nbformat 4.5+ requires."
    ]
   },
   {
@@ -237,8 +237,7 @@
    "id": "20e64f41",
    "metadata": {},
    "source": [
-    "Jupyter adds a trailing <code>\\n</code> to images in cell outputs. Vscode-jupyter does not.\\\n",
-    "Notebooks should be brought to a common style to avoid unnecessary diffs:"
+    "Jupyter adds a trailing `\\n` to images in cell outputs. VS Code's Jupyter extension does not. In this PNG example, `clean_nb` removes the newline to avoid editor-dependent diffs:"
    ]
   },
   {
@@ -259,7 +258,7 @@
    "id": "62dd6b38",
    "metadata": {},
    "source": [
-    "The test notebook has metadata in both the main metadata section and contains cell level metadata in the second cell:"
+    "The test notebook contains notebook metadata and metadata on its second cell:"
    ]
   },
   {
@@ -280,7 +279,7 @@
    "id": "5261f00d",
    "metadata": {},
    "source": [
-    "After cleaning the notebook, all extra metadata is removed, only some keys are allowed by default:"
+    "`clean_nb` keeps the default allowed metadata keys and removes the others:"
    ]
   },
   {
@@ -301,7 +300,7 @@
    "id": "5c387f44",
    "metadata": {},
    "source": [
-    "`clean_nb` also repairs structural problems by default (via `repair_nb`), so notebooks that Jupyter would reject, such as a markdown cell carrying an `outputs` attr, are fixed on every clean:"
+    "`clean_nb` calls `repair_nb` by default to fix invalid notebook structure. For example, Markdown cells must not have `outputs` or `execution_count` attributes:"
    ]
   },
   {
@@ -367,7 +366,7 @@
    "id": "286cb214",
    "metadata": {},
    "source": [
-    "Passing `clean_ids=True` removes `id`s from plaintext repr outputs, to avoid notebooks whose contents change on each run since they often lead to git merge conflicts. For example:\n",
+    "`clean_ids=True` removes object memory addresses from text representations in outputs. These addresses can change between runs and cause unnecessary Git diffs and merge conflicts. For example:\n",
     "\n",
     "```\n",
     "<PIL.PngImagePlugin.PngImageFile image mode=L size=28x28 at 0x7FB4F8979690>\n",
@@ -385,7 +384,7 @@
    "id": "89d0a249",
    "metadata": {},
    "source": [
-    "*Cell* IDs, on the other hand, are always added if missing"
+    "`clean_nb` adds missing cell IDs:"
    ]
   },
   {
@@ -460,7 +459,7 @@
    "source": [
     "## Directive migrations\n",
     "\n",
-    "Deliberate, opt-in rewrites for moving to the directive conventions introduced in v3.3: directives can live in cell metadata (an `nbdev` dict key), notebook-scope directives like `default_exp` can live in notebook metadata, and comment spellings have one canonical form. None of these run by default; they're flags on `nbdev-clean` for one-off migration runs, so the git hook never triggers them."
+    "`nbdev-clean` can rewrite directive comments and move directives into metadata. These migrations require explicit flags. Git hooks never run them."
    ]
   },
   {
@@ -504,7 +503,7 @@
    "id": "233f7207",
    "metadata": {},
    "source": [
-    "`_to_meta` and `_to_comments` move named directives between a cell's comments and its `nbdev` metadata key, preserving values through the same mapping the parser uses (bare directives become `true`, and so on):"
+    "Move selected directives between comments and cell metadata without changing their meaning:"
    ]
   },
   {
@@ -567,7 +566,7 @@
    "id": "bb81ec0f",
    "metadata": {},
    "source": [
-    "`_canon_dirs` respells each directive line canonically without touching anything else, and `_hoist_nb_meta` moves `default_exp` to notebook metadata, deleting a first cell that held nothing but directives (a bare `#| hide` on an otherwise-empty cell hides nothing). `_dir_moves` bundles the migrations for the CLI, converting the raw loaded dict to `NbCell`s first:"
+    "`_canon_dirs` rewrites directive comments in canonical form and leaves other source unchanged. `_hoist_nb_meta` moves `default_exp` into notebook metadata. It removes cells left empty by the move, including those containing only `#| hide`:"
    ]
   },
   {
@@ -644,8 +643,13 @@
    "source": [
     "By default (`fname` left to `None`), all the notebooks in `config.nbs_path` are cleaned. You can opt in to fully clean the notebook by removing every bit of metadata and the cell outputs by passing `clear_all=True`.\n",
     "\n",
-    "If you want to keep some keys in the main notebook metadata you can set `allowed_metadata_keys` in `[tool.nbdev]` in `pyproject.toml`.\n",
-    "Similarly for cell level metadata use `allowed_cell_metadata_keys`, and for output metadata use `allowed_out_metadata_keys`. For example, to preserve both `k1` and `k2` at both the notebook and cell level add the following to `pyproject.toml`:\n",
+    "To preserve extra metadata, use these settings under `[tool.nbdev]` in `pyproject.toml`:\n",
+    "\n",
+    "- `allowed_metadata_keys` preserves notebook metadata.\n",
+    "- `allowed_cell_metadata_keys` preserves cell metadata.\n",
+    "- `allowed_out_metadata_keys` preserves output metadata.\n",
+    "\n",
+    "This example preserves `k1` and `k2` at all three levels:\n",
     "```toml\n",
     "[tool.nbdev]\n",
     "allowed_metadata_keys = [\"k1\", \"k2\"]\n",
@@ -952,7 +956,11 @@
    "source": [
     "See `clean_jupyter` and `nbdev-merge` for more about how each hook works.\n",
     "\n",
-    "Both git drivers are registered under the name `jupyternotebook`, the same name nbdime uses. Repo installs define them in a repo-local `.gitconfig` (wired in via `include.path`) and activate them in the committed `.gitattributes`; `--globally` instead defines them in `~/.gitconfig` and activates them in the global attributes file (`core.attributesFile`, defaulting to `~/.config/git/attributes`). Since the attribute lines just name a driver, a committed `.gitattributes` means \"use your preferred notebook driver\": whichever tool defined `jupyternotebook` last in a config git consults wins, so switching between nbdev and nbdime is just re-running either tool's enable command. Global installs skip the repo-only `post-merge` trust hook."
+    "Both Git drivers use the name `jupyternotebook`, matching nbdime. The attributes file selects this name. Git configuration determines which program runs it. You can therefore commit `.gitattributes` while letting collaborators use their preferred driver.\n",
+    "\n",
+    "A repo installation defines the drivers in `.gitconfig`, included through `include.path`, and activates them in `.gitattributes`. With `--globally`, definitions go in `~/.gitconfig`. Attributes go in `core.attributesFile`, which defaults to `~/.config/git/attributes`.\n",
+    "\n",
+    "Re-running either tool's enable command changes its driver configuration. Git uses the definition with highest precedence. Global installations skip the repo's `post-merge` trust hook."
    ]
   },
   {