Docs/0.2.0 revision

.github/workflows/ci.yaml

@@ -57,6 +57,10 @@ jobs:
         run: pixi run test
       - name: Generated field tables and support matrix are current
         run: pixi run fields-check
+      - name: EB/KI catalogue fragments are current and every cited ID has an entry
+        run: pixi run catalog-check
+      - name: Example figures are current
+        run: pixi run figures-check
 
   gsasii:
     # GSAS-II suite incl. the slow regressions against the committed references.

CHANGELOG.md

@@ -5,7 +5,7 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and PowderLine
 versions follow [Semantic Versioning](https://semver.org/).
 
 The recipe **schemas** are versioned separately from the package and have their
-own history, [`docs/SCHEMA_HISTORY.md`](docs/SCHEMA_HISTORY.md).
+own history, on the [versions page](docs/reference/versions.md).
 
 ## [Unreleased]
 
@@ -14,15 +14,15 @@ own history, [`docs/SCHEMA_HISTORY.md`](docs/SCHEMA_HISTORY.md).
 PowderLine 0.2.0 is a clean break from the unified recipe schema 0.26.0: a
 recipe names one engine and is written in that engine's own conventions, and
 nothing is translated between engines. Recipes written for 0.1.x do not
-validate; see the [migration guide](docs/migration-0.1-to-0.2.md). Known
-limitations are listed in the [known-issues register](docs/known_issues.md).
+validate; see the [migration guide](docs/development/migrating-from-0.1.md). Known
+limitations are listed in the [known-issues register](docs/reference/known-issues.md).
 
 ### Highlights
 
 - **One recipe, one engine:** `gsasii.*`, `topas.*` and `easydiffraction.*`
   recipes, each in its engine's own names and units, through one API and one CLI.
 - **New schemas, starting at 0.1.0:** a core schema plus one schema per engine
-  replace the single 0.1–0.26.0 schema ([schemas](docs/schemas.md)).
+  replace the single 0.1–0.26.0 schema ([engines](docs/engines/index.md)).
 - **Validation states what the engine computes:** symmetry, engine floors and
   silent defaults become errors or structured warnings, never silent changes.
 - **Uniform fit statistics:** `rwp`, `r_exp`, `gof`, `chi2_red` are computed by
@@ -34,7 +34,7 @@ limitations are listed in the [known-issues register](docs/known_issues.md).
 
 ### Upgrading
 
-- Read the [migration guide](docs/migration-0.1-to-0.2.md): a 0.26.0 recipe
+- Read the [migration guide](docs/development/migrating-from-0.1.md): a 0.26.0 recipe
   (`GSASII_Rietveld` / `GSASII_SPF`) is refused at `schema_name`.
 - Convert gsasii recipes with `python scripts/convert_recipe_026.py IN.json -o
   OUT.json`; it reports every change and stops where 0.1.1's refinement cannot
@@ -52,10 +52,10 @@ limitations are listed in the [known-issues register](docs/known_issues.md).
 
 - Engine schemas `gsasii.rietveld` / `gsasii.spf` (GSAS-II 5.7.9),
   `topas.rietveld` / `topas.spf` (TOPAS 6) and `easydiffraction.rietveld`
-  (easydiffraction 0.21.1), on a shared core phase block ([fields](docs/fields.md)).
+  (easydiffraction 0.21.1), on a shared core phase block ([fields](docs/reference/fields.md)).
 - Declared schema compatibility: each gateway states the core and engine schema
   versions it accepts, `validate()` enforces them, and `powderline.support_matrix()`
-  lists them ([support matrix](docs/support-matrix.md)).
+  lists them ([support matrix](docs/reference/versions.md)).
 - `powderline.validate()`, engine-free, returning `ValidationResult(recipe,
   warnings)`; an invalid recipe raises pydantic's `ValidationError` listing every
   problem at its field path.
@@ -74,7 +74,7 @@ limitations are listed in the [known-issues register](docs/known_issues.md).
   with value and ESD, by GSAS-II's own name.
 - Ionic `scattering_types` (CIF spelling, e.g. `La3+`) per atom label in the
   gsasii and easydiffraction (`cryspy`) phase blocks, checked against each
-  engine's ion table ([input guidance](docs/input-guidance.md); EB-94–EB-96).
+  engine's ion table ([scattering types by engine](docs/engines/index.md); EB-94–EB-96).
 - March–Dollase `preferred_orientation` (`hkl`, `ratio`) in the gsasii and
   easydiffraction (`cryspy`) phase blocks (EB-97, EB-98).
 - TOPAS accepts ionic `scattering_types` (TOPAS 6's table, 113 ions, written as
@@ -95,16 +95,26 @@ limitations are listed in the [known-issues register](docs/known_issues.md).
 - Examples: per-engine recipes under `examples/<case>/{topas,easydiffraction}/`,
   `example_LaB6_temperature_series` (sequential refinement), `example_LaB6_ionic`
   and `example_LaB6_textured`, with easydiffraction references.
-- Documentation: [schemas](docs/schemas.md), [fields](docs/fields.md), [input
-  guidance](docs/input-guidance.md), [engine behaviour](docs/engine-behavior.md),
-  [cross-engine comparison](docs/cross-engine-comparison.md), [policies](docs/policies.md).
-- Engine citations in `CITATION.cff` and on the [citing page](docs/citing.md) (#12).
+- Documentation, organised by reader: Get started, Concepts, How-to guides,
+  Examples, Engines, Reference and Development, on pydata-sphinx-theme with
+  diagrams and per-engine tabs ([docs](https://nsls2.github.io/PowderLine/)).
+  Among its pages: [outputs](docs/reference/outputs.md),
+  [fields](docs/reference/fields.md), [validation](docs/concepts/validation.md),
+  [engine behaviour](docs/engines/index.md),
+  [cross-engine comparison](docs/concepts/comparing-engines.md) and
+  [policies](docs/development/policies.md).
+- Every engine behaviour (`EB-NN`) and known issue (`KI-NN`) has its own
+  entry and link, listed in the [ID index](docs/reference/ids.md). Known
+  issues KI-19 to KI-21 cover the GSAS-II server's lifetime, its state
+  directory and a race in `gsas-server stop`
+  ([known issues](docs/reference/known-issues.md)).
+- Engine citations in `CITATION.cff` and on the [citing page](docs/about/citing.md) (#12).
 
 ### Changed
 
 - The recipe schema is split: the single 0.1–0.26.0 schema is replaced by a
   core schema and one schema per engine, each starting at **0.1.0** and told
-  apart by `schema_name`; the 0.x bump rule is in [policies](docs/policies.md).
+  apart by `schema_name`; the 0.x bump rule is in [policies](docs/development/policies.md).
 - A recipe names its engine and workflow in `schema_name` (`<engine>.<workflow>`)
   and states that engine's own terms and units; unknown keys are errors at
   every level.
@@ -178,6 +188,14 @@ limitations are listed in the [known-issues register](docs/known_issues.md).
   the LaB6 examples drop their undeterminable background peak.
 - The simulation recipe builder writes SH/L 0.002 (GSAS-II's floor) and emits a
   `gsasii.rietveld` 0.1.0 recipe.
+- CLI and GSAS-II server messages name the current commands: `pixi run
+  powderline …`, `pixi install --frozen -e <env>`, `pixi run -e gsasii
+  gsas-server stop` for a stale server (the next run starts a fresh one),
+  `pixi run -e gsasii gsas-server start`, and `pixi reinstall powderline
+  --all`.
+- Messages say what they mean: an atom near a special position reports the
+  distance to its symmetry image, and the GSAS-II background-default warning
+  says GSAS-II's own default background is fixed.
 
 ### Removed
 

CONTRIBUTING.md

@@ -1,76 +1,37 @@
 # Contributing to PowderLine
 
-Thanks for your interest! This page is the map; the detail lives in the linked
-guides.
+Thanks for your interest. This page is the short version. The full guide is
+the [Development section](https://nsls2.github.io/PowderLine/development/) of
+the docs: architecture, setup, tests, the docs build, adding an engine, and
+the policies.
 
-## Dev setup
+## Set up
 
 ```bash
-git clone https://github.com/NSLS2/PowderLine.git
-cd PowderLine
-pixi install -e dev   # every engine + docs/test tooling (GSAS-II is built as a conda package)
-pixi run test         # full suite (dev env) — run it before and after your change
-pixi run docs         # Sphinx with -W; zero warnings is the standard
+pixi install --frozen -e dev            # every engine + docs and test tooling
+git config core.hooksPath scripts/hooks # the pre-commit guard, once per clone
+pixi run test                           # the engine-free suites
 ```
 
-The default environment is core-only (it validates recipes for every engine
-and runs none); `pixi install -e gsasii` / `-e easydiffraction` install one
-engine. After pulling a change to `pyproject.toml`'s entry points, run
-`pixi reinstall powderline --all`.
-
-[pixi](https://pixi.sh) is the only tool you install yourself. See the
-[README](README.md) for platforms and the [Quickstart](docs/quickstart.md) for
-a first refinement run.
-
-## Where things are
-
-- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** — developer guide:
-  architecture (core + gateways), the schema layer, **how to add a refinement
-  engine or a capability**, GSAS-II integration, workflow.
-- **[docs/policies.md](docs/policies.md)** — what binds every change:
-  versioning and declared compatibility, deliberate behaviour changes, the
-  frozen GSAS-II modules, engine-version pins, review, "ask, don't
-  assume".
-- **[docs/engine-behavior.md](docs/engine-behavior.md)** — what each engine
-  does with a recipe and PowderLine's policy toward it.
-- **[docs/known_issues.md](docs/known_issues.md)** — the known-issues register
-  (`KI-NN` ids, referenced from code and docs): check it before "fixing" a
-  quirk. See also [docs/regression-tolerance.md](docs/regression-tolerance.md)
-  (why numeric comparisons are tolerance-based) and
-  [docs/cross-platform-guide.md](docs/cross-platform-guide.md).
-- **[examples/CONTRIBUTING_EXAMPLES.md](examples/CONTRIBUTING_EXAMPLES.md)** —
-  how to contribute a new example recipe (examples drive schema evolution).
-
-## Design records
-
-Maintainers keep design records in a separate private repository.
-`_dev/` is reserved and gitignored; never commit it.
-
-Dev-doc scaffold paths (`docs/superpowers/`, `docs/plans/`, `docs/specs/`,
-`docs/dev/`), `.gpx` binaries, `fort.*` scratch, and `_dev/` are all rejected by
-the pre-commit guard so they never reach `main`.
+[pixi](https://pixi.sh) is the only tool you install yourself.
 
 ## Ground rules
 
-- Branch off `main`; keep commits reviewable and self-contained.
-- Enable the pre-commit guard once per clone:
-  `git config core.hooksPath scripts/hooks`. It blocks accidental commits of
-  data files outside the sanctioned dirs, `.gpx` binaries, and the private
-  `_dev/` workspace.
-- Run `pixi run test` before opening a PR. Some regression cases need a working
-  GSAS-II refinement — compare failures against a baseline run, don't assume
-  they're yours.
+- Branch off `main` and keep commits reviewable and self-contained.
+- Run the tests before and after your change, and compare against `main`:
+  some GSAS-II regression cases can fail for environment reasons.
+- Keep `pixi run docs` free of warnings. After editing a schema or a gateway's
+  declarations, regenerate the field tables (`pixi run fields-check` tells you
+  when they are stale).
 - The frozen GSAS-II modules
   (`src/powderline/gateways/gsasii/{helpers,project,setters,executors,extractors,constraints}.py`)
-  change only through the maintainers' signed-off record of frozen-code
-  edits; after such an edit run `pixi run update-code-hash`. Restart the GSAS-II server after
-  editing anything it runs (`pixi run -e gsasii gsas-server restart`).
-- After editing a schema module or a gateway's version declarations, run
-  `PYTHONPATH=src python scripts/gen_schema_field_tables.py` and commit the
-  regenerated `docs/_generated/` fragments.
-- If a decision is not written down (policies page, schema history), ask the maintainer rather than inferring it.
-- `examples/**/output/` is tracked on purpose (regression references) — don't
-  regenerate it casually.
+  change behaviour only with the maintainers' explicit consent. Comment and
+  docstring edits are fine. After any edit, run `pixi run update-code-hash`.
+- `examples/**/output/` is tracked on purpose (regression references). It
+  moves only as a deliberate, reviewed change.
+- If a decision is not written down, ask the maintainers rather than infer
+  it.
+- AI-assisted commits end with an `Assisted-by: <agent>:<model>` trailer.
 - Questions and bug reports: open a GitHub issue.
 
 ## Changelog