specmod 0.2.1__tar.gz → 0.2.2__tar.gz

{specmod-0.2.1 → specmod-0.2.2}/.github/workflows/docs.yml

@@ -33,7 +33,12 @@ jobs:
 
       # The package itself, not just the docs extra: autodoc imports every
       # module it documents, so a docs build is also an import check.
-      - run: uv pip install -e ".[docs,io]"
+      #
+      # `tutorial` supplies the Jupyter kernel. `docs/conf.py` executes the
+      # tutorial notebook on every build instead of trusting committed outputs,
+      # so without ipykernel the build fails on a missing kernel. Keep this list
+      # in step with `.readthedocs.yaml`, which installs the same three.
+      - run: uv pip install -e ".[docs,io,tutorial]"
 
       - name: Build
         # No -W. Intersphinx resolves seven inventories over the network and

{specmod-0.2.1 → specmod-0.2.2}/.gitignore

@@ -26,6 +26,11 @@ htmlcov/
 
 # Docs
 docs/_build/
+# `docs/conf.py` copies `tutorial/` here so Sphinx can build the notebook from
+# inside its source directory, with the data it reads by relative path. The
+# copy is also what the notebook's own output lands in, which is the point —
+# executing it where it lives would write into the working tree.
+docs/tutorial/
 
 # Editors / OS
 .ftpconfig
@@ -39,9 +44,12 @@ docs/_build/
 
 # Tutorial output. Regenerated by running the notebook; committing it means a
 # diff every time anyone executes it, and a stale copy the moment the pipeline
-# changes. The inputs (Tutorial/Data, Tutorial/MetaData) *are* committed.
-Tutorial/Spectra/*.h5
-Tutorial/Spectra/FlatFiles/
+# changes. The inputs — waveforms, stations, picks — *are* committed.
+#
+# These patterns named `Tutorial/Spectra/` until now, the capitalised layout
+# from before the `src/` move, so they had matched nothing for the whole
+# refactor and the three files below were tracked in spite of the rule above.
+tutorial/data/events/*/spectra/
 
 # Created by `uv run` without --no-sync; this project resolves fresh on
 # purpose so the floors job can test the declared minimums.

{specmod-0.2.1 → specmod-0.2.2}/.readthedocs.yaml

@@ -42,6 +42,12 @@ python:
       extra_requirements:
         # `io` alongside `docs` because autodoc imports every module it
         # documents, and `specmod.io` imports h5py and pyarrow. Without it the
-        # API reference loses those pages to import errors.
+        # API reference loses those pages to import errors — and the tutorial
+        # saves an HDF5 file, so it needs them at execution time too.
         - docs
         - io
+        # `tutorial` supplies the Jupyter kernel. `docs/conf.py` executes the
+        # notebook on every build rather than trusting committed outputs, which
+        # needs ipykernel, nbclient and nbformat present. Without it the build
+        # fails on a missing kernel rather than quietly publishing stale cells.
+        - tutorial

specmod-0.2.2/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.2"
+}

{specmod-0.2.1 → specmod-0.2.2}/CHANGELOG.md

@@ -9,6 +9,18 @@ release could have this problem — every later one has a real predecessor tag
 so leave subsequent headings as generated. release-please only prepends to this
 file, so this edit survives. -->
 
+## [0.2.2](https://github.com/sgjholt/SpecMod/compare/v0.2.1...v0.2.2) (2026-09-05)
+
+
+### Bug Fixes
+
+* ignore the tutorial output at the path it is actually written to ([ad34cc7](https://github.com/sgjholt/SpecMod/commit/ad34cc7d44208e5bd49a2d1f1277516670848dc7))
+
+
+### Documentation
+
+* publish the tutorial, executed on every build ([ccd1842](https://github.com/sgjholt/SpecMod/commit/ccd18429b9da5db875885d88269fb70686e6eaa3))
+
 ## [0.2.1](https://github.com/sgjholt/SpecMod/compare/v0.2.0...v0.2.1) (2026-08-23)
 
 

{specmod-0.2.1 → specmod-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specmod
-Version: 0.2.1
+Version: 0.2.2
 Summary: A Python toolbox for processing and modelling seismic spectra
 Project-URL: Homepage, https://github.com/sgjholt/SpecMod
 Project-URL: Repository, https://github.com/sgjholt/SpecMod

{specmod-0.2.1 → specmod-0.2.2}/docs/conf.py

@@ -14,7 +14,9 @@ gives.
 
 from __future__ import annotations
 
+import shutil
 from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
 
 project = "SpecMod"
 author = "James Holt"
@@ -32,7 +34,9 @@ except PackageNotFoundError:  # pragma: no cover - docs built without an install
 version = ".".join(release.split(".")[:2])
 
 extensions = [
-    "myst_parser",
+    #: `myst_nb` supersedes `myst_parser` — it is a superset, and loading both
+    #: makes Sphinx complain that the `.md` parser is registered twice.
+    "myst_nb",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
@@ -45,9 +49,10 @@ extensions = [
 
 #: `REFACTOR_PLAN.md` is a working document, not documentation — it is written
 #: for whoever is doing the refactor and records decisions and their evidence.
-#: `notebooks/` is built by Phase 6 with myst-nb; until then the `.ipynb` files
-#: would be copied in without being executed, which is worse than leaving them
-#: out. `notes/` *is* included: `choosing-a-transform.md` links to it for a
+#: `notebooks/` holds the source for the transform comparison, which
+#: `tools/measure_docs.py` renders into `choosing-a-transform.md`; the page is
+#: what is published, so building the notebook too would duplicate it.
+#: `notes/` *is* included: `choosing-a-transform.md` links to it for a
 #: per-trace table, so excluding it broke that link.
 exclude_patterns = [
     "_build",
@@ -57,9 +62,58 @@ exclude_patterns = [
     ".DS_Store",
 ]
 
-#: Markdown only. Every page in `docs/` is already written that way, and
-#: allowing both means two syntaxes for the same job.
-source_suffix = {".md": "markdown"}
+# ------------------------------------------------------- the tutorial notebook
+
+#: The tutorial lives in `tutorial/`, outside this source directory, next to the
+#: 1 MB of PNR waveforms it reads through paths relative to itself. Sphinx only
+#: builds what is under `docs/`, so it is copied in here.
+#:
+#: A copy rather than a move, and rather than executing it where it sits,
+#: because **the notebook writes**: cell 53 saves an HDF5 file under
+#: `data/events/<event>/spectra/` and cell 54 writes flatfiles beside it. Run in
+#: place, a docs build would leave those artefacts in the working tree — which
+#: is why `tests/test_tutorial.py` executes it in a `tmp_path` copy too. This is
+#: the same trick, and the copy is what the artefacts land in.
+#:
+#: Copying the data with it is what keeps the notebook's `Path("data/events")`
+#: working, so the notebook is identical whether opened from `tutorial/`, run by
+#: pytest, or built here. `tutorial/` stays canonical: eight other files name
+#: `tutorial/data/events/`, and the CI job that executes it records that a
+#: renamed data directory has already broken this once.
+_HERE = Path(__file__).parent
+_TUTORIAL_SRC = _HERE.parent / "tutorial"
+_TUTORIAL_DST = _HERE / "tutorial"
+
+if _TUTORIAL_SRC.is_dir():
+    shutil.rmtree(_TUTORIAL_DST, ignore_errors=True)
+    shutil.copytree(_TUTORIAL_SRC, _TUTORIAL_DST)
+
+#: `force`, not `auto`. `auto` executes only notebooks that arrive without
+#: outputs, and the tutorial is committed *with* 28 cells of them — so `auto`
+#: would publish whatever was last saved by hand, which is the silent rot this
+#: is meant to end. Forcing it means the page can only show output the code
+#: actually produced against the code being documented.
+nb_execution_mode = "force"
+#: Matches `tests/test_tutorial.py`. The whole notebook runs in ~40s; the
+#: default 30s is per cell, and the two-stage fit is the one that would trip it.
+nb_execution_timeout = 600
+#: A notebook that raises fails the build. That is the point: an executed
+#: tutorial is only a guarantee if a broken one is loud.
+nb_execution_raise_on_error = True
+#: `False` keeps the kernel's working directory at the notebook's own, which is
+#: what `Path("data/events")` resolves against.
+nb_execution_in_temp = False
+
+#: Markdown for the prose pages — every one in `docs/` is written that way, and
+#: allowing reStructuredText too would mean two syntaxes for the same job — plus
+#: `.ipynb` for the tutorial.
+#:
+#: Both map to `myst-nb`, which is the only parser name `myst_nb` 1.4 registers:
+#: it does not re-register `myst_parser`'s `markdown`, so leaving `.md` pointing
+#: at that fails the build outright with "Source parser for markdown not
+#: registered". The `myst-nb` parser is a superset and reads the prose pages
+#: identically.
+source_suffix = {".md": "myst-nb", ".ipynb": "myst-nb"}
 
 #: `linkify` is deliberately absent: it needs `linkify-it-py` and every link in
 #: these pages is already explicit.

{specmod-0.2.1 → specmod-0.2.2}/docs/documentation.md

@@ -195,8 +195,11 @@ pages can link to each other's sections.
   those work; without it MyST does not read `$` at all.
 - `amsmath` is **not** enabled — nothing here uses a bare `\begin{align}`
   outside `$` delimiters. A `\begin{cases}` inside `$$` renders without it.
-- Markdown only. `source_suffix` maps `.md`; there is no reStructuredText in
-  `docs/`, so there is one syntax rather than two.
+- Markdown and notebooks. `source_suffix` maps `.md` and `.ipynb`, both to
+  `myst-nb` — there is no reStructuredText in `docs/`, so there is one prose
+  syntax rather than two. Both suffixes name `myst-nb` because that is the only
+  parser `myst_nb` registers; pointing `.md` at `myst_parser`'s `markdown`
+  fails the build with "Source parser for markdown not registered".
 - For a Sphinx directive that has no MyST spelling, drop into rST:
 
 ````markdown
@@ -225,6 +228,40 @@ Type hints come from the annotations via `autodoc_typehints = "description"`.
 `sphinx-autodoc-typehints` is deliberately **not** used: measured, it produced
 the same 367 documented objects while calling an API Sphinx 10 removes.
 
+### The tutorial notebook
+
+`tutorial/SpecModTutorial.ipynb` is published as part of the site and
+**executed on every build** (`nb_execution_mode = "force"`). Every figure and
+number on the page came from running that code against the code being
+documented, and a notebook that raises fails the build
+(`nb_execution_raise_on_error = True`). That is the whole point: a tutorial
+nobody runs is the first thing to rot, and this one broke three times before
+anything executed it.
+
+Three things about the arrangement are worth knowing before changing it.
+
+**It is copied into `docs/tutorial/` by `conf.py`, not moved.** Sphinx builds
+only what is under `docs/`, and the notebook reads its 1 MB of waveforms
+through paths relative to itself — so the data has to travel with it. The copy
+is gitignored. `tutorial/` stays canonical because eight other files name
+`tutorial/data/events/`, and a renamed data directory has broken this before.
+
+**The copy is also what the notebook writes into.** It saves an HDF5 file and
+two flatfiles as part of the lesson. Executed where it lives, a docs build
+would leave those in your working tree; `tests/test_tutorial.py` copies to
+`tmp_path` for exactly the same reason.
+
+**Outputs are stripped in git**, by the `nbstripout` pre-commit hook, and
+regenerated at build time. Do not commit them back: `force` ignores them, so a
+committed output is never what a reader sees — only a stale diff.
+
+The kernel comes from the `tutorial` extra. Both `.readthedocs.yaml` and
+`.github/workflows/docs.yml` install `[docs,io,tutorial]`; keep them in step or
+one of the two builds fails on a missing kernel. This does mean the notebook
+executes twice per pull request — once here and once in the `notebook` CI job,
+which also checks imports and that deleted modules stay unmentioned. Roughly
+40 seconds, paid twice, for two genuinely different failures.
+
 ### Numbers in prose
 
 Any table that came from a measurement is generated, not typed. Edit

{specmod-0.2.1 → specmod-0.2.2}/docs/index.md

@@ -45,6 +45,11 @@ print(fits.table[["id", "llpsp", "fc", "ts"]])
 
 ## Where to start
 
+[Tutorial](tutorial/SpecModTutorial.ipynb)
+: One event end to end — waveforms and picks in, source parameters out. Every
+  figure and number on the page is produced by running the notebook at build
+  time, so it cannot describe an API that no longer exists.
+
 [Processing](processing.md)
 : Every step of the pipeline with the equation it implements — what a window
   is, how the noise is compared against it, and what the bandwidth selector
@@ -97,6 +102,7 @@ one either way.
 :maxdepth: 2
 :hidden:
 
+tutorial/SpecModTutorial
 processing
 choosing-a-transform
 pick-formats

{specmod-0.2.1 → specmod-0.2.2}/docs/roadmap.md

@@ -102,15 +102,24 @@ What is left: `io.py` and `plotting.py` are still single modules, and the
 operations that mutate in place need to return new objects instead. Neither is
 large — the split is about responsibilities, not line count.
 
+### The tutorial, executed
+
+The tutorial is published as part of this site and **re-executed on every
+build**, so every figure and number on the page came from running the code
+being documented. A notebook that stops working fails the build rather than
+going quietly stale, which is what it was listed as a 1.0 requirement for.
+
 ## Planned
 
 ### 1.0 — the API stops moving
 
-The theory page that states the normalisation and units conventions
-explicitly, the tutorial rebuilt as an executed notebook so it cannot rot
-silently, and a "what changed since 0.1" guide for anyone upgrading. Then the
-1.0 release, which is the promise that names and signatures stop moving
-without a deprecation cycle.
+Two things left: the theory page that states the normalisation and units
+conventions explicitly, and a "what changed since 0.1" guide for anyone
+upgrading. Then the 1.0 release, which is the promise that names and
+signatures stop moving without a deprecation cycle.
+
+The third — the tutorial rebuilt as an executed notebook, so it cannot rot
+silently — is merged and sits under *In progress* above until it ships.
 
 That promise is the whole content of the number, which is why it has to be a
 decision rather than something a breaking commit does on its way past. Until