specmod 0.2.1__tar.gz → 0.2.3__tar.gz

{specmod-0.2.1 → specmod-0.2.3}/.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.3}/.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.3}/.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.3/.release-please-manifest.json

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

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

@@ -9,6 +9,35 @@ 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.3](https://github.com/sgjholt/SpecMod/compare/v0.2.2...v0.2.3) (2026-09-05)
+
+
+### Bug Fixes
+
+* correct four documented equations and behaviours that the code contradicts ([821792b](https://github.com/sgjholt/SpecMod/commit/821792b66d418b9c0048d717975b5a3716c52c20))
+* point the DOI badge at the concept DOI, not v0.2.0's ([11e7f7a](https://github.com/sgjholt/SpecMod/commit/11e7f7a056fc17c91b22c1dc9d834f19b8b6dbe3))
+
+
+### Documentation
+
+* an upgrade guide, and a table of contents with a shape ([4f35388](https://github.com/sgjholt/SpecMod/commit/4f353885cfd0768edeac225d7db4672a20c9120e))
+* derive the roadmap's version, and say when its entries move ([1917d43](https://github.com/sgjholt/SpecMod/commit/1917d432c6fdae1969dacb506bdac986152e40d8))
+* document moment and magnitude, which the page said were absent ([026abec](https://github.com/sgjholt/SpecMod/commit/026abecb9c6ed33017b306e825a6f84db2b343e4))
+* state what is true now, not what the page used to say ([b17339b](https://github.com/sgjholt/SpecMod/commit/b17339b6ad383afd936f7f2a972549b313e19906))
+* the documentation 1.0 was waiting on is done ([9693334](https://github.com/sgjholt/SpecMod/commit/9693334434738ae000bf61f1908524ee983ced17))
+
+## [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.3}/CITATION.cff

@@ -12,7 +12,7 @@ identifiers:
   # mints a version DOI per release; cite that one instead when reproducibility
   # matters and you need the reader to land on the exact version you ran.
   - type: doi
-    value: "10.5281/zenodo.22071455"
+    value: "10.5281/zenodo.22071454"
     description: "Concept DOI — resolves to the latest release."
 keywords:
   - seismology

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specmod
-Version: 0.2.1
+Version: 0.2.3
 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
@@ -38,6 +38,7 @@ Provides-Extra: docs
 Requires-Dist: myst-nb>=1.1; extra == 'docs'
 Requires-Dist: myst-parser>=3.0; extra == 'docs'
 Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'docs'
+Requires-Dist: sphinx-togglebutton>=0.3; extra == 'docs'
 Requires-Dist: sphinx>=7.3; extra == 'docs'
 Provides-Extra: io
 Requires-Dist: h5py>=3.11; extra == 'io'
@@ -58,7 +59,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/specmod.svg)](https://pypi.org/project/specmod/)
 [![Documentation](https://readthedocs.org/projects/specmod/badge/?version=stable)](https://specmod.readthedocs.io/en/stable/)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071455.svg)](https://doi.org/10.5281/zenodo.22071455)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071454.svg)](https://doi.org/10.5281/zenodo.22071454)
 
 A Python toolbox for processing and modelling seismic spectra, following the
 method of Edwards *et al.* (2010).
@@ -237,7 +238,7 @@ The full documentation — the pipeline with its equations, the estimator
 comparison, pick formats, and an API reference — builds with Sphinx:
 
 ```bash
-uv pip install -e '.[docs]'
+uv pip install -e '.[docs,io,tutorial]'
 sphinx-build -b html docs docs/_build/html
 ```
 

{specmod-0.2.1 → specmod-0.2.3}/README.md

@@ -2,7 +2,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/specmod.svg)](https://pypi.org/project/specmod/)
 [![Documentation](https://readthedocs.org/projects/specmod/badge/?version=stable)](https://specmod.readthedocs.io/en/stable/)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071455.svg)](https://doi.org/10.5281/zenodo.22071455)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071454.svg)](https://doi.org/10.5281/zenodo.22071454)
 
 A Python toolbox for processing and modelling seismic spectra, following the
 method of Edwards *et al.* (2010).
@@ -181,7 +181,7 @@ The full documentation — the pipeline with its equations, the estimator
 comparison, pick formats, and an API reference — builds with Sphinx:
 
 ```bash
-uv pip install -e '.[docs]'
+uv pip install -e '.[docs,io,tutorial]'
 sphinx-build -b html docs docs/_build/html
 ```
 

{specmod-0.2.1 → specmod-0.2.3}/docs/choosing-a-transform.md

@@ -253,11 +253,8 @@ or **0.03 magnitude units**. Against the 0.13 m.u. scatter quoted for spectral
 `Mw` that is small, but it is systematic rather than random, so it does not
 average away across stations at similar distance.
 
-> Earlier revisions of this page reported 89% for flat weighting and 650% for
-> adaptive here. The 650% was the adaptive collapse described above and is
-> gone. The remaining figures come from a differently-constructed sweep than
-> the original and are not directly comparable to it; this table is the one
-> `tools/measure_docs.py` reproduces.
+> Every figure in this table is regenerated by `tools/measure_docs.py`, and
+> `tests/test_docs_are_current.py` fails if the page and the code disagree.
 
 ### It costs you a diagnostic
 

specmod-0.2.3/docs/conf.py

@@ -0,0 +1,190 @@
+"""Sphinx configuration for the SpecMod documentation.
+
+Build with::
+
+    uv pip install -e '.[docs,io,tutorial]'
+    sphinx-build -b html docs docs/_build/html
+
+``-W`` is deliberately **not** used. Intersphinx resolves seven inventories
+over the network, and a warning is emitted whenever one of them is briefly
+unreachable — turning a third party's downtime into a red build. The docs job
+fails on a non-zero exit instead, which is what a genuinely broken build
+gives.
+"""
+
+from __future__ import annotations
+
+import shutil
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+project = "SpecMod"
+author = "James Holt"
+#: Sphinx substitutes `%Y` with the build year, so this does not need editing
+#: — and it honours `SOURCE_DATE_EPOCH`, so a reproducible build stamps the
+#: source date rather than the day it happened to run. 2020 is the year in
+#: `LICENSE` and the year the history starts.
+copyright = "2020-%Y, James Holt"
+
+try:
+    release = version("specmod")
+except PackageNotFoundError:  # pragma: no cover - docs built without an install
+    release = "0.0.0"
+#: The short X.Y form, which is what the sidebar shows.
+version = ".".join(release.split(".")[:2])
+
+extensions = [
+    #: `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",
+    "sphinx.ext.viewcode",
+    #: Makes `:class: dropdown` collapse an admonition. The alpha warning on the
+    #: landing page is the reason: it has to be read once and then stops earning
+    #: the screen it occupies, and a caveat nobody scrolls past is worse than
+    #: one folded behind its own headline.
+    "sphinx_togglebutton",
+]
+#: `sphinx_autodoc_typehints` is deliberately not used. `autodoc_typehints`
+#: below is built into `sphinx.ext.autodoc` and does the same job here, and the
+#: extension calls an API Sphinx 10 removes — it emits a deprecation warning
+#: per module on Sphinx 9. One less dependency for no loss.
+
+#: `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/` 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",
+    "REFACTOR_PLAN.md",
+    "notebooks/*",
+    "Thumbs.db",
+    ".DS_Store",
+]
+
+# ------------------------------------------------------- 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`. The `nbstripout` hook means the notebook arrives with no
+#: outputs, so `auto` would execute it today and quietly stop the moment anyone
+#: committed a notebook with outputs saved — publishing whatever was last run by
+#: hand. Forcing it means the page can only ever show output the code produced
+#: against the code being documented, whatever is in the file.
+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.
+myst_enable_extensions = [
+    "colon_fence",  # ::: fences, so a directive can hold a code block
+    "deflist",
+    "dollarmath",
+    "substitution",
+]
+#: Heading anchors down to h3, so `docs/*.md` can link to each other's sections.
+myst_heading_anchors = 3
+
+#: `{{ release }}` in a page resolves to the version this site was built from.
+#: The roadmap used to state it in prose, which meant it was wrong from the
+#: moment of the next release — it said v0.2.0 through two that followed. A
+#: version is derivable, so deriving it removes the only part of that page that
+#: went stale on a timetable rather than on a decision.
+myst_substitutions = {"release": release}
+
+# ------------------------------------------------------------------ autodoc
+
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+    "member-order": "bysource",
+}
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
+    "pandas": ("https://pandas.pydata.org/docs", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "obspy": ("https://docs.obspy.org", None),
+    "lmfit": ("https://lmfit.github.io/lmfit-py", None),
+}
+#: Resolving these needs the network. A build without it still produces a
+#: site, with the cross-references left as plain text.
+intersphinx_disabled_reftypes = ["*"]
+
+# --------------------------------------------------------------------- html
+
+html_theme = "pydata_sphinx_theme"
+html_title = f"{project} {version}"
+html_theme_options = {
+    "github_url": "https://github.com/sgjholt/SpecMod",
+    "show_prev_next": True,
+    "navigation_with_keys": False,
+    #: This theme puts *top-level* toctree entries in the header and gives the
+    #: sidebar the current section's children. A flat toctree therefore
+    #: produces a header of ten items and an empty sidebar, with `:caption:`
+    #: nowhere to render — which is what this site had. The four section pages
+    #: are what give the sidebar something to nest.
+    #:
+    #: `show_nav_level: 1` expands each section's own entries rather than
+    #: leaving them behind a disclosure triangle, so a reader can see a
+    #: section's contents without a click.
+    "show_nav_level": 1,
+    #: Deep enough for a section, its pages, and their headings — which is what
+    #: makes a long page like `processing` navigable from the sidebar rather
+    #: than by scrolling.
+    "navigation_depth": 3,
+}
+html_static_path: list[str] = []

specmod-0.2.3/docs/contributing.md

@@ -0,0 +1,31 @@
+# Working on SpecMod
+
+Where the project is going, how to work on it, and how a merged commit becomes
+a release.
+
+[Roadmap](roadmap.md)
+: What has shipped and in which version, what is being worked on, and what 1.0
+  will mean. Milestones, not dates.
+
+[Developer guide](development.md)
+: Quick start, the repository mapped, the daily loop, every tool and check, and
+  where development stops and releasing begins. Includes working with coding
+  agents.
+
+[Documentation workflow](documentation.md)
+: Building this site locally, previewing a pull request's build, how the
+  tutorial is executed into it, and how to add a page.
+
+[Releasing the software](releasing.md)
+: How a merged commit becomes a tag, a PyPI release and a DOI — and the
+  one-time repository settings none of it works without.
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+roadmap
+development
+documentation
+releasing
+```

{specmod-0.2.1 → specmod-0.2.3}/docs/development.md

@@ -246,12 +246,12 @@ bounded rather than explained, and says so in as many words.
 
 ## What CI runs
 
-Five jobs in `test.yml`, plus two more workflows. All of them run on every pull
-request.
+Six jobs in `test.yml`, plus three more workflows. All of them run on every
+pull request except `release.yml`, which fires only on a push to `main`.
 
 | Job | Workflow | Does |
 |---|---|---|
-| `lint` | `test.yml` | `ruff check`, `ruff format --check`, and the `ci/` mirror check |
+| `lint` | `test.yml` | `ruff check` and `ruff format --check` over `src/ tests/ tools/` |
 | `typecheck` | `test.yml` | `mypy`, strict, over the whole package |
 | `test` | `test.yml` | pytest on 3.11/3.12/3.13 × ubuntu/macOS, coverage to Codecov from one cell |
 | `floors` | `test.yml` | installs the *declared minimum* versions and runs the suite |
@@ -403,9 +403,12 @@ has happened here:
   not there. Three commits went out with session trailers before this was
   noticed; the config now installs both hook types from one command, and the
   first thing `AGENTS.md` says is to run it.
-- **An agent's token cannot push `.github/workflows/`.** This is what the
-  `ci/` mirror exists for. An agent that does not know about it will either
-  fail the push or, worse, quietly drop the change.
+- **An agent's token may not be able to push `.github/workflows/`.** The
+  permission is granted here now, and the `ci/` mirror that used to work around
+  it is gone — keeping two copies of every workflow in step cost more than the
+  problem it solved. If the permission is ever withdrawn the push is rejected
+  loudly, naming `workflows`; the answer is to ask for it back, not to rebuild
+  the mirror.
 - **A development container often lacks the optional extras**, so an agent's
   green run can be greener than CI's. `--without-optional-extras` is the check.
 - **A harness may append its own commit trailers.** The repository's rules take

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

@@ -32,7 +32,7 @@ those are separate clocks.
 ## Building it locally
 
 ```sh
-uv pip install -e '.[docs]'
+uv pip install -e '.[docs,io,tutorial]'
 sphinx-build -b html docs docs/_build/html
 python -m http.server -d docs/_build/html 8000   # then open localhost:8000
 ```
@@ -136,9 +136,11 @@ Two things in it are load-bearing and easy to lose:
   clones shallow to save time, and `hatch-vcs` derives the version from
   `git describe`. Without those two lines every build — including a tagged one
   — reports the fallback `0.0.0` in the sidebar.
-- **`extra_requirements: [docs, io]`.** The `io` extra is there because autodoc
-  imports `specmod.io`, which imports h5py and pyarrow. The CI job installs the
-  same pair for the same reason.
+- **`extra_requirements: [docs, io, tutorial]`.** `io` because autodoc imports
+  `specmod.io`, which imports h5py and pyarrow — and because the tutorial saves
+  an HDF5 file while executing. `tutorial` for the Jupyter kernel that executes
+  it. The CI `docs` job installs the same three for the same reasons; keep them
+  in step or one of the two builds fails on a missing kernel.
 
 ## Versions, and what to link to
 
@@ -168,11 +170,19 @@ page depends on is documentation whatever its folder is called.
 ### Adding a page
 
 1. Write `docs/<name>.md` in MyST Markdown.
-2. Add it to the `toctree` at the bottom of `docs/index.md`, and usually to the
-   "Where to start" list above it.
+2. **Add it to the `toctree` of the section it belongs to** — not to
+   `index.md`. The site has four section pages, each owning its own toctree:
+   `getting-started.md`, `guides.md`, `api.md` and `contributing.md`. Add a
+   description to the list on that page too, since the sidebar shows titles
+   only.
 3. Build. A page in no toctree builds but warns, and is reachable only by a
    direct link.
 
+`index.md`'s toctree holds only those four. That is what gives the sidebar its
+nesting: this theme puts top-level toctree entries in the header and gives the
+sidebar the current section's children, so a page added at the top level lands
+in the header and flattens the navigation for everything else.
+
 If a page is a supporting note rather than a top-level one, put it in a hidden
 toctree on the page that cites it — that is how `notes/window-position.md` is
 attached to `choosing-a-transform.md`:
@@ -195,8 +205,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
@@ -223,7 +236,44 @@ the first build:
 
 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 same number of 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 runs the single `-m notebook` test that executes it in a `tmp_path` copy.
+Roughly 40 seconds, paid twice, to catch a broken notebook either as a failed
+build or as a failed test. The cheaper checks around it — that every name the
+notebook imports resolves, and that deleted modules stay unmentioned even in
+prose — are unmarked, so they run in the `test` matrix job instead.
 
 ### Numbers in prose
 

specmod-0.2.3/docs/getting-started.md

@@ -0,0 +1,41 @@
+# Getting started
+
+Install it, run one event end to end, and find out what moved if you have code
+written against `0.1`.
+
+```sh
+pip install specmod
+```
+
+Python 3.11 or newer. Saving and loading spectra needs the `io` extra —
+`pip install "specmod[io]"` — without which SpecMod computes and plots normally
+but cannot write a result. The other extras are listed in the
+[README](https://github.com/sgjholt/SpecMod#installation).
+
+While this is `0.x`, pin an exact version in anything you intend to publish.
+The [roadmap](roadmap.md) says what has shipped and what 1.0 will mean.
+
+[Tutorial](tutorial/SpecModTutorial.ipynb)
+: One event from waveforms and picks to source parameters. Every figure and
+  number on the page is produced by executing the notebook when this site is
+  built, so it cannot describe an API that no longer exists. **Start here.**
+
+[Upgrading from 0.1](upgrading.md)
+: For code written against the pre-refactor `0.1.1` on `master`. Modules moved,
+  were renamed to snake_case, and several were deleted, so old code fails at
+  its imports rather than running and quietly giving different numbers.
+
+## Then
+
+[How a spectrum is processed](processing.md) is the reference for what each
+stage does and the conventions it uses — the amplitude convention, the Parseval
+contract, and the moment and magnitude equations. It is the page to read once
+the tutorial has run.
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+tutorial/SpecModTutorial
+upgrading
+```

specmod-0.2.3/docs/guides.md

@@ -0,0 +1,55 @@
+# Guides
+
+What each stage does, why it is done that way, and what the choices cost.
+
+## The pipeline, and the conventions
+
+[How a spectrum is processed](processing.md)
+: Every step from a raw waveform to a moment magnitude, with the equation it
+  applies and a pointer to the code that applies it.
+
+This is also where the conventions are stated, deliberately in the sections
+that apply them rather than on a page of their own:
+
+[Amplitude convention](processing.md#4-amplitude-convention)
+: `FAS` is the folded $2\lvert X\rvert$; `MAGNITUDE` is the unfolded
+  $\lvert X\rvert$, **and that is the one $\Omega$ is defined in**. Reading a
+  folded plateau as $\Omega$ puts $M_0$ out by two — 0.2 magnitude units.
+
+[The Parseval contract](processing.md#the-parseval-contract)
+: The one energy check every estimator is held to, which is what lets
+  multitaper, Welch, FFT and the CWT be interchangeable rather than merely
+  similar.
+
+[Moment and magnitude](processing.md#9-moment-and-magnitude)
+: The $M_0$ and $M_w$ equations, the medium constants and where they come
+  from, and the two distances that are in different units on purpose.
+
+## Choices that change the answer
+
+[Choosing a transform](choosing-a-transform.md)
+: What each estimator does to your data, measured. On real windows the plateau
+  moves by 7–15% between estimators — about 0.03 magnitude units — and window
+  position alone reaches 0.08. Small against the 0.13 m.u. scatter quoted for
+  spectral $M_w$, but systematic rather than random, so it does not average
+  away across stations at similar distance.
+
+[Reading picks](pick-formats.md)
+: What arrival formats are read out of the box, how to add one, and how a pick
+  is matched to a trace.
+
+## Working with data
+
+[Publishing a dataset](releasing-data.md)
+: Taking an event from an FDSN archive to a hash-pinned entry in the registry,
+  so a result can be reproduced from the same bytes.
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+processing
+choosing-a-transform
+pick-formats
+releasing-data
+```