samplekit 1.0.0rc1__tar.gz → 1.0.0rc2__tar.gz

{samplekit-1.0.0rc1 → samplekit-1.0.0rc2}/CHANGELOG.md

@@ -7,6 +7,303 @@ SampleKit rather than works on it.
 A version ending in `-rc.N` is a release candidate: tried before the version
 of that number is published, and replaced by it.
 
+## [1.0.0-rc.2] — 2026-11-04
+
+The second release candidate of SampleKit 1.0 (`1.0.0rc2` for Python).
+
+### Upgrading from 1.0.0-rc.1
+
+Sample files are unchanged. **`samplekit-migrate.pyz`**, attached to this
+release, makes the renames below in a copy of a project, its samples copied as
+they are. It reads projects of 0.1.0 to 0.2.0 too: their samples, and their
+model's declarations written again, its formulas copied to check by hand. It
+works on a copy and guarantees nothing: back your project up first. [Upgrade from an older
+SampleKit](https://zelyph.github.io/SampleKit/latest/guides/upgrade.html) says
+how to run it, and each step to do by hand; in short:
+
+- **Before upgrading, bring every value up to date with rc.1**: `samplekit
+  DIR status`, then `samplekit DIR compute --write`. This version does not
+  read rc.1's record of which formula computed each value: at its first write
+  in a project, it takes the values the files hold as computed by the model
+  as it is then, and says how many.
+- **Install the command line and the Python package together**, at the same
+  version, on every computer that shares a project.
+- **Add `python = ".venv"` under `[model]`** in `.samplekitrc`, or the path of
+  another environment or interpreter: the model runs only in the Python named
+  there.
+- **Rename what changed name**: `[workbench.colors]` is `[colors]`, the
+  colour role `stale` is `outdated`, a style's `separator` is written as its
+  `property`, `{collection}` in a path is `{project}`; in Python, `stale()` and `is_stale` are `outdated()` and
+  `is_outdated`. Each old name is refused, naming the new one.
+- `new --like SAMPLE` is `new NAME --keep SAMPLE FIELDS`.
+- **Rename a property's formulas, in this order**: `compute=` becomes
+  `compute_value=`, then `compute_quantity=` becomes `compute=`. No value is
+  outdated by it. A value formula left as `compute=` still runs, but then owns
+  the whole property: an uncertainty typed beside it is no longer kept.
+
+### Cleaning up after rc.1
+
+Nothing breaks if you leave these, but they are no longer used:
+
+- **In the state folder** (`~/.local/state/samplekit` on Linux,
+  `~/Library/Application Support/samplekit` on macOS,
+  `%LOCALAPPDATA%\samplekit` on Windows): `computed.json`, `computed`, `consent`, `accepted/`, and the run logs named `logs/compute-YYYY-MM-DDT…Z-PID.log` can be deleted.
+  `samplekit-migrate.pyz --clean-state` lists them, and removes them with
+  `--write`.
+- **A history shared through git under rc.1** committed files that each
+  computer keeps for itself. Remove them from the repository once, then add
+  `[history] shared = true` (below): `git rm -r --cached
+  .samplekit/history/HEAD .samplekit/history/config
+  .samplekit/history/description .samplekit/history/hooks
+  .samplekit/model.json`, then `git add -A`.
+- **A value restored from a snapshot rc.1 took** has no record of the formula
+  that computed it, and is taken as current: if that formula changed since,
+  compute it again, `samplekit DIR compute -p NAME --rerun --write`.
+
+### Added
+
+- **A migration tool**, `samplekit-migrate.pyz`, attached to each release: a
+  project of 0.1.0, 0.1.1, 0.1.2, 0.2.0 or 1.0.0-rc.1, carried into a new
+  folder this version reads, and a report of what was carried, left and to
+  check by hand. Run with the Python of an environment where this version's
+  package is installed; it installs nothing and never writes in the folder it
+  reads.
+- **An export writes a figure**: `[export.curves]` with `figure = "curves"`
+  and `output = "paper/curves.pdf"`, where a table's names its `profile`.
+  `samplekit export curves --write` then draws it to its file, as a table for
+  a paper is written again; Python's `export("curves")` and the TUI's `p`
+  menu do the same.
+- **A project's look decides more of its figures**: what `[matplotlib]`
+  declares wins over SampleKit's own choices, so `"lines.marker" = "None"`
+  draws a `line` figure without markers, and `errorbar.capsize` sets the
+  error bars' caps. `style` applies matplotlib's style sheets, by name or as
+  `.mplstyle` files, and `fonts` makes font files kept in the project known
+  to matplotlib. A figure takes settings of its own: `matplotlib = { … }` in
+  `[figure.NAME]`, `@sk.figure(matplotlib={…})` in a model.
+- **`import` takes a file, and a list**: `import = ["..",
+  "figures.samplekitrc"]` merges the folder above's `.samplekitrc` and a file
+  of any name, a later one over an earlier one, so that a project's settings
+  can be kept in files of their own. [Organise a project's
+  settings](https://zelyph.github.io/SampleKit/latest/guides/organise-settings.html)
+  shows how.
+- **An environment made by uv works**: `samplekit init` installs the package
+  into a `.venv/` without pip with `uv pip install`, when uv is on the
+  `PATH`, and otherwise says the command to type.
+- **Write a command in any order**: `samplekit samples status`, `samplekit
+  status samples` and `samplekit -f 'mass > 10' status samples` are the same,
+  and a list of files piped in works, `… | xargs samplekit status`. Where a
+  folder has a command's name, the command wins; write the folder `status/`.
+- **Select samples on every command**: `-f` (a filter) and `--query` (a
+  filter saved in `.samplekitrc`) now work with `set`, `log`, `diff`,
+  `restore`, `validate`, `list`, `explain` and `open` too. `samplekit samples
+  set -f 'material == steel' supplier=acme` previews each sample it changes,
+  asks once, and writes them together.
+- **Every change is previewed, then asked**: `set`, `new`, `tag`, `export`,
+  `restore` and `compute` show what they would change and end on `apply these
+  changes? [y/N]`. `--write` answers yes beforehand, for scripts.
+- **Documents in LaTeX, Markdown or HTML**: a style, `[style.NAME]` in
+  `.samplekitrc`, says how values, units and tables are written for a kind of
+  document. `latex`, `markdown` and `html` are given: `samplekit samples --style
+  latex -c name,density -o table.tex` writes a LaTeX table ready to include.
+- **Filters reach into tables**: `results has 42`, a sample with 42 in any cell
+  of its `results` table; `results.status has failed`, in one column; and
+  `results where (temperature > 100 && status == failed)`, one row meeting
+  both. A filter also compares two fields of a sample: `measured >
+  expected`.
+- **Scripts in the model**: a method of the model marked `@sk.script` is an
+  action on a sample or on a selection, with options; `samplekit run NAME`
+  runs it, or `p` in the TUI, and what it changes is previewed before it is
+  written.
+- **Share the history through git with one line**: `[history] shared = true`
+  in `.samplekitrc`, and `git add -A` takes the history with the samples;
+  SampleKit keeps out what each computer makes for itself.
+- **A folder made a project keeps its history**: when a subfolder gets its own
+  `.samplekitrc`, the snapshots the project above it took of its files are
+  copied into its own history, and this is said.
+- **In the TUI**: a value, a table or a list opens in a window where each cell
+  is edited, readings and list items included; `A` adds an attribute to a
+  sample, its name then its value; `p` runs a script, draws a figure or writes
+  an export from one menu, for the basket, the sample open or the samples
+  shown.
+- **Save what a table shows**: `--save query=NAME`, `profile=NAME` or
+  `export=NAME` on a table declares its filter, its columns, sort and groups,
+  or both and an export, in `.samplekitrc`, previewed first; the TUI's `W`
+  does the same.
+- **Remove a sample**: `samplekit FILE remove` deletes sample files, previewed
+  first; the history keeps them, and `restore` gives them back. A folder alone
+  is refused. In Python, `sample.remove()`.
+- **The note from the command line**: `set note=…` replaces the text below
+  the frontmatter, and `note=` empties it.
+- **Links**: an attribute written `"[[steel-02]]"`, as Obsidian writes a
+  link, names another sample of the project; one written as Markdown does,
+  `"[certificate](../certificates/c.pdf)"`, a file by its path, a sample of
+  any project or any other file; one written `https://…` a web page. A list
+  of links names several. The TUI opens each with `Enter` or `o`, a sample
+  even where the filter leaves it out, its title bar saying the way taken
+  and `Esc` going back along it; Python reads the samples with
+  `sample.linked("reference")`, a file that is no sample as its path; and
+  `validate` reports a link that leads nowhere. A link is shown as Markdown
+  shows it, its text alone, underlined in the colour role `link`, `↗` after a
+  web page and `✗` after one leading nowhere, in the TUI, and in a table and
+  `view` drawn in a terminal; typed, written to a file or a pipe, it is the
+  text written. Unquoted, a link is refused at its line, saying to quote it.
+  A sample's screen lists the samples linking to it, and the filter `links to
+  NAME` selects the samples whose links name it; `set parents=[[a]],[[b]]` writes a list of links, and
+  Tab after `[[` completes a sample's name, on `set` and in the TUI.
+- **Rename a sample**: `samplekit FILE rename NEW` renames its file, its own
+  files and its `name`, and writes every link of the project leading to it
+  again, a link to one of its own files too, previewed first; in the TUI, `R`;
+  in Python, `sample.rename(new)`. `remove` lists the links it leaves leading
+  nowhere.
+- **A sample's own table written to a file**: `samplekit FILE view curve`
+  shows the table `curve` alone, and `--csv`, `--tsv`, `--json` or `-o
+  curve.csv` write its rows, previewed and kept in the history as a table of
+  samples is; over several samples, a column `name` first. In Python,
+  `sample.curve.to_csv()`.
+- **A script may ask with `input()`**: on the command line in the terminal,
+  in the TUI in the script's window, which shows what it prints as it prints
+  it. The preview lists the answers, and the history keeps them with the
+  command.
+- **The TUI does what the command line does**: `C` previews what it would
+  compute, as `compute` does; in `H`, `r` puts files back as a change left
+  them, `d` shows what a change changed and, on another, compares the two; `t` renames a tag, `old=new`; `N` takes a
+  new sample's values, `field=value`, and fields kept from another,
+  `keep:FIELD,…`; `D` removes a sample.
+- **An editor of its own window leaves the TUI drawn**: with Notepad or
+  `code --wait`, `E` and `M` say what they wait for over the TUI; an editor
+  in the terminal takes it as before.
+- **Windows**: tab completion in PowerShell completes the word after the
+  cursor, where each Tab wrote the word before it again; `E` and `M` open
+  the file in Notepad where no editor is named, rather than in the
+  application Windows gives it (Python, for a model); a sample's folder is
+  shown in Explorer, its file selected; a lock or a journal a killed command
+  left is taken back; paths are said with `\`, never with both separators in
+  one message.
+- `new NAME --keep SAMPLE FIELDS` copies the fields named from another
+  sample, and nothing else; `[property.NAME] range = [MIN, MAX]` makes a value
+  outside the range a defect for `validate`; `compute --timeout SECONDS`
+  stops a formula that runs too long and computes the others.
+
+### Changed
+
+- **The demo is a tensile test**: three metal specimens in five steps, from
+  their sizes written by hand to their curves, results, a paper's tables and
+  figures, and two projects read together; in its results, two specimens
+  link to the one they are compared with. The start page writes it, and
+  *Reset the demo* writes it again as it came.
+- **The documentation is in three parts**: guides, a task each; concepts, how
+  SampleKit works and why; and the reference. The home page walks through the
+  demo, and a page at an address of rc.1 sends its reader on. New guides
+  install SampleKit, start a project, edit, find and link samples, work in
+  the terminal interface and from Python, organise settings, read several
+  projects together, and say what to do when something goes wrong.
+- **`note` is a reserved name**: a file holding an attribute `note:` is
+  refused, saying to rename it `remarks:` or `comment:`; `set note=` and
+  `sample.note` are the text below the frontmatter.
+- **A number typed is previewed as the table shows it**: `set area=25.0`
+  beside an uncertainty of `0.028` previews `25.000`, and `25.0123` keeps
+  every digit typed.
+- **A new row makes what reads its column outdated**: after `set --add-row`,
+  a value reading a computed column is *outdated*, as are the values reading
+  it, where it was said to wait for the new cell.
+- **`compute` counts unchanged values by cells**, as it counts what it
+  computed: `computed 61 values in 3 samples, all unchanged`.
+
+- **An uncertainty is rounded up, never understated**: at `.3f`, an
+  uncertainty of 0.00006 is written `0.001`, and 0.121 at `.2f` is `0.13`,
+  where rc.1 wrote `0.000` and `0.12`. A value is still rounded to the
+  nearest. The screen, Python and every file write the same digits, and a
+  standard error in a summary is rounded up too. An uncertainty is never
+  written as zero, so `validate` and an export no longer warn of one.
+- **A property's formulas are `compute`, `compute_value` and
+  `compute_uncertainty`**: `compute=f` gives the whole property, `f()`
+  returning a number or `(value, uncertainty)`; `compute_value=` the value
+  alone, beside an uncertainty given apart. They were `compute_quantity`,
+  `compute` and `compute_uncertainty`.
+- **A table's columns are declared with `sk.Property`**, its formula with
+  them: `sk.Property(unit="MPa", compute=self._stress,
+  depends_on=["row.force", "area"])`, the function given each row and
+  returning its cell, or `compute_column=f`, given the columns it reads and
+  returning one cell per row; `compute_value` and `compute_uncertainty` give
+  one number of each cell, the other entered. `sk.Column` is gone. A formula filling several
+  columns at once is a `sk.ComputedColumns`, in the table's `computed=`;
+  `compute_rows` and `compute_columns` are gone. A cell a formula gives is a
+  number or `(value, uncertainty)`, as a property's is, where the pair was
+  refused.
+- **A project reads its subfolders by default**: `[collection] recursive` is
+  `true` unless `.samplekitrc` says `false`, so that `samplekit .` at a
+  project's root reads `samples/`. A folder outside any project is read alone,
+  as before. A folder reading no sample says so, naming the folders below that
+  hold some.
+- **A table names its index**: `sk.Table(columns, index="day")`, or
+  `index=["day", "hour"]`; the index given by position is refused.
+- **The command line is in colour on a terminal**, with the TUI's colours: a
+  value bold, an attribute and a unit each in its colour, a header bold, a
+  state as the TUI shows it, `✓` and `written:` in green. One palette,
+  `[colors]`, sets both; a file and a pipe get none.
+- **Numbers in a column line up**: a column of numbers is written to the
+  decimals of its most precise, `2.00` beside `1.99`; a column of values with
+  uncertainties to one number of decimals where every uncertainty can keep one
+  or two significant digits (two when the first is a 1), `12.503 ± 0.004`
+  above `12.513 ± 0.010`. A summary's median, minimum and maximum follow
+  their column, and `set` says the mean of new readings to the place of their
+  uncertainty. A declared precision still wins.
+- **The record of which formula computed each value travels with the
+  project**, in its history, no longer on your computer: a formula edited on
+  one computer is seen changed on every other, and a colleague's
+  recomputed values are current on yours.
+- **Reading computes nothing, in Python too**: a value computed from readings,
+  the mean of several measurements, say, has no value until it is
+  computed, and says *never computed*, rather than computing behind your back.
+- **A file written from values that are not current says so and exits 2**: an
+  export or a table written with `-o` names the values that are outdated,
+  failed or never computed. In a CSV, a column `NAME_state` beside the
+  quantity says which.
+- **Exports write units as the sample files spell them**, `degC` rather than
+  the screen's `°C`; `--style plain` gives the screen's forms.
+- **`restore` without `--at` takes back your last change only**, value by
+  value, and keeps what was edited by hand or pulled from a colleague since.
+- **A sample file must declare `schema_version: 1`**; a file without it is not
+  a sample, as a README is not. A key written twice in a sample is refused
+  rather than silently taking the last.
+- **In the TUI**: a value opens selected, so that what you type replaces it
+  (an arrow or `End` keeps it to edit); the basket is kept from one session
+  to the next; a file changed in another editor is read again by itself.
+
+- **Values not current are counted by cells**, on every surface: a table's
+  column outdated in its 13 rows counts 13, and a value and its uncertainty
+  given by two formulas count two.
+- **What reads a waiting value waits too**, said *waits for area, which
+  waits*, rather than outdated or failed. A value the model no longer
+  computes is listed apart, to keep or remove.
+- **One wording for nothing done**: a command with nothing to change says
+  `nothing to change — WHY`, and a question answered no says `nothing
+  written`.
+- **`validate` reads each sample with the model**, and says where the model
+  cannot read one.
+- **A file written from values not current says so on the standard output**,
+  so that `-q` or a redirected error stream does not hide it; `--accept
+  waiting` is refused, since a waiting value fails nothing.
+- **Over several projects, a snapshot's number is one project's**: `log
+  --at`, `diff --from` and `--to` from a folder above several projects are
+  refused, naming the project to choose.
+- **The migration tool keeps every sample's note**, 0.x's included.
+
+### Removed
+
+- **Reading what earlier versions wrote**: sample files, configuration keys,
+  command-line words and Python names of SampleKit 0.2 and rc.1 are refused
+  like any unknown one, naming the nearest valid name. The upgrade guide says
+  how to carry each over.
+- `new --like`, `compute --try`, and the folder after `explain FILE`: a file
+  SampleKit wrote is now found in the projects around it.
+
+### Fixed
+
+Many defects found by testing rc.1, among them values reported as current
+that were not, edits lost when two changes met, and a colleague's work pulled
+through git that the history took for your own.
+
 ## [1.0.0-rc.1] — 2026-09-28
 
 The first release candidate of SampleKit 1.0, and a new SampleKit. Version
@@ -334,9 +631,9 @@ model's description is current.
   `'value' is written 'v' since schema 1: rename it`.
 - **`template()` and the `report` module**: the note is no longer generated.
   Tables for a paper are profiles and exports; figures are drawn with `plot`.
-- **pandas**: `to_dataframe()`, `stats()` on a list and the `converters`
-  module. `to_csv()` or `to_dict()` give data pandas reads, and `--summary`,
-  `Summary` and `sk.stats` summarise.
+- **pandas**: `to_dataframe()` and the `converters` module; `stats()` on a
+  list gives a `Summary` rather than a DataFrame. `to_csv()` or `to_dict()`
+  give data pandas reads, and `--summary`, `Summary` and `sk.stats` summarise.
 - **Computing on read**, and the cache a changed input cleared.
 - **The automatic mean and standard deviation of a list**: a statistic is
   declared.
@@ -345,7 +642,7 @@ model's description is current.
 
 No command converts a 0.2.0 sample: the model has to be rewritten by hand
 anyway, and a tool that did half the work would take all the risk of writing
-to your files. [Upgrade from an older SampleKit](docs/how-to/upgrade.md)
+to your files. [Upgrade from an older SampleKit](docs/guides/upgrade.md)
 shows how to carry each sample across — its values, uncertainties, readings,
 tables and text — with both versions installed side by side, into a new
 folder, and how to check the result.

{samplekit-1.0.0rc1 → samplekit-1.0.0rc2}/Cargo.lock

@@ -1462,6 +1462,12 @@ version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
+[[package]]
+name = "html-escape"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c9356095b4b41197bba32173600e1582792cda618f65d12f68e2e77d273413c5"
+
 [[package]]
 name = "iana-time-zone"
 version = "0.1.65"
@@ -2473,7 +2479,7 @@ dependencies = [
 
 [[package]]
 name = "samplekit"
-version = "1.0.0-rc.1"
+version = "1.0.0-rc.2"
 dependencies = [
  "anstream",
  "anstyle",
@@ -2489,6 +2495,7 @@ dependencies = [
  "gethostname",
  "gix",
  "globset",
+ "html-escape",
  "indexmap",
  "nucleo-matcher",
  "opener",
@@ -2508,8 +2515,10 @@ dependencies = [
  "toml_edit",
  "tui-markdown",
  "unicode-ident",
+ "unicode-normalization",
  "unicode-segmentation",
  "unicode-width",
+ "v_latexescape",
  "walkdir",
 ]
 
@@ -3035,6 +3044,21 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
+[[package]]
+name = "v_escape-base"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1212fce830b75af194b578e55b3db9049f2c8c45f58d397fb25602fdb50fb3d"
+
+[[package]]
+name = "v_latexescape"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67ee1d1c03d7a41c6540f932756c9eb9bab23f02877c6337c5629a29aad942f1"
+dependencies = [
+ "v_escape-base",
+]
+
 [[package]]
 name = "version_check"
 version = "0.9.5"
@@ -3241,9 +3265,9 @@ dependencies = [
 
 [[package]]
 name = "yoke-derive"
-version = "0.8.3"
+version = "0.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "33811428bee40dbceb6d545e95754741d17a6aef9a4849f0fd62e2ba4f412a78"
+checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71"
 dependencies = [
  "proc-macro2",
  "quote",

{samplekit-1.0.0rc1 → samplekit-1.0.0rc2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "samplekit"
-version = "1.0.0-rc.1"
+version = "1.0.0-rc.2"
 edition = "2024"
 description = "Sample data in plain Markdown: computed, current, tracked"
 repository = "https://github.com/zelyph/SampleKit"
@@ -17,7 +17,7 @@ include = [
     "/Cargo.lock",
     "/build.rs",
     "/src/",
-    "/examples/brewing/",
+    "/examples/tensile/",
     "/README.md",
     "/CHANGELOG.md",
     "/LICENSE",
@@ -45,6 +45,7 @@ serde_json = { version = "1", features = ["raw_value"] }
 toml = { version = "0.9", features = ["preserve_order"] }
 unicode-width = "0.2"
 unicode-segmentation = "1"
+unicode-normalization = "0.1.25"
 anstyle = "1.0"
 anstream = "1.0"
 anstyle-parse = "1.0"
@@ -57,6 +58,8 @@ ctrlc = { version = "3.5.2", features = ["termination"] }
 toml_edit = "0.25"
 ratatui = { version = "0.30", default-features = false, features = ["crossterm"] }
 gix = { version = "0.88", default-features = false, features = ["sha1"] }
+# Writes the history's pack when it is compacted: the versions gix uses, with
+# the features that write a pack and its index.
 crossterm = "0.29"
 tui-markdown = { version = "0.3.9", default-features = false }
 nucleo-matcher = "0.3.1"
@@ -73,6 +76,8 @@ shell-words = "1.1.1"
 gethostname = "1.1.0"
 rat-text = "3.1.0"
 rat-markdown = "0.7.3"
+v_latexescape = "0.16"
+html-escape = "0.2"
 
 [lints.clippy]
 all = { level = "deny", priority = -1 }

samplekit-1.0.0rc2/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: samplekit
+Version: 1.0.0rc2
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: matplotlib>=3.8
+License-File: LICENSE
+License-File: THIRD-PARTY-LICENSES.md
+Summary: Sample data in plain Markdown: computed, current, tracked
+Keywords: samples,notebook,markdown,uncertainty
+Home-Page: https://zelyph.github.io/SampleKit/
+Author: zelyph
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/zelyph/SampleKit/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://zelyph.github.io/SampleKit/latest/
+Project-URL: Homepage, https://github.com/zelyph/SampleKit
+Project-URL: Issues, https://github.com/zelyph/SampleKit/issues
+
+# SampleKit
+
+**Sample data in plain Markdown: computed, current, tracked.**
+
+Which value was computed from which measurement? Was this table made before or
+after the thickness was measured again? Is the figure in the draft still
+right? SampleKit answers these questions for a folder of plain text files:
+one sample, one Markdown file, readable in any editor, in Obsidian, and in
+git.
+
+```yaml
+---
+schema_version: 1
+name: copper-01
+material: copper
+compared_with: "[[steel-01]]"
+properties:
+  width: {readings: [12.509, 12.498, 12.506], unit: mm}
+  thickness: {readings: [1.995, 1.988, 2.007], unit: mm}
+---
+Tested at 2 mm/min, across the rolling direction.
+```
+
+Above the second `---` are the sample's data: attributes, values with their
+uncertainties and units, readings, tables of measurements. Below is a note
+that is yours, kept as you write it. A folder of such files is a project,
+with no database and nothing to set up.
+
+## What it does
+
+- **Computed**: the values that derive from your measurements, an area, a
+  modulus, a whole column of stress, come from formulas you write in Python,
+  uncertainties included.
+- **Current**: SampleKit knows which results still rest on the measurements
+  they were computed from, and says which do not, and why.
+- **Tracked**: every change it writes is kept in a history of the project's
+  own, with the command that made it, and no git to install. `--at` reads the
+  project as it was, and makes a table or a figure again exactly as it was.
+- **Tables and figures**: select, sort and group samples, then write a CSV, a
+  LaTeX or Markdown table, or a matplotlib figure, in one style for the whole
+  project, by one command you run again at each draft.
+- **Linked**: a sample names another, a file or a web page, as Obsidian and
+  Markdown write a link; SampleKit follows it both ways, checks it, and keeps
+  it when a sample is renamed.
+- **Three ways in**: a command line, a full-screen terminal interface, and a
+  Python package reading the same files with the same names.
+
+## A taste
+
+From the last step of the demo, three tensile specimens:
+
+```console
+$ samplekit -c name,material,tensile_strength -s -tensile_strength   # a table, sorted
+$ samplekit -f 'elongation > 20'                  # the specimens a filter selects
+$ samplekit status                                # what is not current, and why
+$ samplekit compute --write                       # run the project's Python model
+$ samplekit export paper --write                  # a LaTeX table for a paper
+$ samplekit samples/steel-01.md view curve --csv  # a sample's curve, as CSV
+$ samplekit samples/steel-01.md log               # every change kept, and what made it
+$ samplekit                                       # the terminal interface, full screen
+```
+
+```python
+import samplekit as sk
+
+for specimen in sk.load("samples").filter("elongation > 20"):
+    print(specimen.name, specimen.young_modulus.value, specimen.young_modulus.uncertainty)
+```
+
+## Install
+
+The command line is one file: download it for Linux, macOS or Windows from
+[the releases](https://github.com/zelyph/SampleKit/releases), or build it with
+Rust:
+
+```console
+$ cargo install samplekit --locked --version VERSION
+```
+
+The Python package goes into each project's `.venv/`, at the version of the
+command line, `VERSION` being what `samplekit --version` says; `samplekit
+init` makes that environment and installs it for you:
+
+```console
+$ pip install samplekit==VERSION
+```
+
+> **Until 1.0, name the version.** `pip install samplekit` alone gives 0.2.0,
+> the previous version, whose API is not this one; likewise the *Latest*
+> release on GitHub is 0.2.0, and this version's archives are under its own
+> release, marked *pre-release*.
+
+[Install SampleKit](https://zelyph.github.io/SampleKit/latest/guides/install.html)
+says more, system by system. **From an earlier version**, 0.x or 1.0.0-rc.1,
+`samplekit-migrate.pyz`, in each release, carries a project into a new
+folder this version reads, and says what to check by hand
+([upgrade](https://zelyph.github.io/SampleKit/latest/guides/upgrade.html)).
+It never writes in the folder it reads; back your project up all the same.
+
+## Try the demo
+
+`samplekit` alone opens its start page; `g`, then *The demo*, writes a
+tensile test in five steps, from three specimens measured by hand to their
+curves, results, a paper's tables and figures, and opens the first.
+[The documentation](https://zelyph.github.io/SampleKit/latest/) walks
+through it, then goes further: guides a task each, the concepts, and the
+reference.
+
+## Where things are
+
+|                                                                                                 |                                                                                                                                                                                                                                                                                                  |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`docs/`](https://zelyph.github.io/SampleKit/latest/index.html)                                 | The documentation: the home page's walkthrough of the demo, [guides](https://zelyph.github.io/SampleKit/latest/guides/index.html), [concepts](https://zelyph.github.io/SampleKit/latest/concepts/index.html) and the [reference](https://zelyph.github.io/SampleKit/latest/reference/index.html) |
+| `src/`, `tests/`                                                                                | The Rust crate: the core, the command line, the terminal interface and the Rust half of the Python package; a test file per source file                                                                                                                                                          |
+| `python/samplekit/`                                                                             | The Python half of the Python package                                                                                                                                                                                                                                                            |
+| [`examples/tensile/`](https://github.com/zelyph/SampleKit/blob/main/examples/tensile/README.md) | The demo, in five steps, generated from `fixtures/tensile/`; the start page writes it for you                                                                                                                                                                                                    |
+| `fixtures/tensile/`                                                                             | What the demo is generated from: its model, scripts and READMEs, and the generator                                                                                                                                                                                                               |
+| [`migrate/`](https://github.com/zelyph/SampleKit/blob/main/migrate/README.md)                   | The migration tool, `samplekit-migrate.pyz` in each release                                                                                                                                                                                                                                      |
+
+## Building
+
+```console
+$ cargo build --release                  # the command line: target/release/samplekit
+$ python -m venv .venv && source .venv/bin/activate
+$ pip install maturin
+$ maturin develop --release              # the Python package, into .venv
+$ tools/check.sh                         # everything a commit must pass
+```
+
+The documentation is a Sphinx site, built from `docs/` into `target/site`,
+after `maturin develop`, since the Python reference reads the package:
+
+```console
+$ .venv/bin/pip install -r docs/requirements.txt
+$ .venv/bin/sphinx-build docs target/site
+```
+
+The command line needs no Python to read, select, render, check or export;
+Python runs a project's model, and matplotlib draws its figures.
+
+## Status
+
+Version `1.0.0-rc.2` (`1.0.0rc2` as Python spells it), the second release
+candidate of `1.0.0`. It follows `0.2.0`, the previous implementation, in
+Python alone, published under the same name. What changed is in
+[CHANGELOG.md](https://github.com/zelyph/SampleKit/blob/main/CHANGELOG.md).
+
+## Roadmap
+
+In order of priority:
+
+- [ ] **1.0**: this release candidate, tried, then published as `1.0.0`;
+  from then on, `pip install samplekit` gives it without naming a version.
+- [ ] **Designs of experiments**: full and
+  fractional factorials, central composite, Box-Behnken, definitive
+  screening and mixture designs, with centre points, replicates, blocks and
+  a randomised order. SampleKit lays out a plan's runs, makes a sample of
+  each, takes in the samples already made, says which runs are still to
+  make, and analyses what they measured: a model per response, reduced and
+  tested term by term, its residuals examined, then used to predict,
+  optimise and draw; in the terminal interface and from Python too.
+- [ ] **An Obsidian plugin**, so that a project opened as a vault shows its
+  properties and tables as SampleKit does, hides what only SampleKit reads,
+  such as `schema_version`, and edits them.
+
+## Licence
+
+MIT: see [LICENSE](https://github.com/zelyph/SampleKit/blob/main/LICENSE).
+Keep the notice with any copy; everything else is permitted, including
+commercial use.
+