📝 docs: reorganise the docs and add the missing tutorials

[nstarman]

Reorganises the documentation — the core docs/ tree and all seven unxts.* package doc sets — into tutorials, how-to guides, reference and explanation, and adds the tutorials that were missing. 17 commits, each independently reviewable.

Why

Everything practitioner-facing lived either on index.md or in a guides/ bucket that mixed instruction, description and rationale in one page. guides/quantity.md was reference, how-to and explanation at once; index.md was a landing page, an install guide, a quickstart tour and an ecosystem page fused together. There was no tutorial anywhere — every entry path assumed the reader already knew why they wanted unitful arrays.

The package doc sets had the same problem in the same place. In unxts.hypothesis and unxts.interop.xarray the landing page had grown longer than the guide it linked to and duplicated it section by section. In unxts.api the rationale for the whole design was inside an HTML comment.

Core docs/ — 22 pages → 37, nothing deleted

index.md              router
tutorials/            first-quantity, mars-lander, dimensional-analysis
how-to/               13 guides
reference/            quantity, units, unitsystems, dimensions,
                      configuration, dataclassish, glossary, api/
explanation/          sharp-bits, why-quantity-is-non-parametric,
                      equality-and-equivalence, api-conventions
about/                contributing, citation + ecosystem

The rationale for the non-parametric default previously existed in migration.md, a guides/quantity.md admonition, README.md and unxts.parametric/docs/index.md — four copies of one argument. It now has one home.

Package doc sets — 27 pages → 38

Each kept a flat tree, with the page's kind carried by its title and a grouped index, rather than growing four subfolders: they are 2–6 pages each and already sit one level down in the nav.

Tutorials

There were none. There are now twelve — five core, one per package — each executed end to end, with every output block real output from that run, and each running in the test suite.

Where	Tutorial	The lesson
core	Your first calculation with units	Build a projectile calculator, then jit, differentiate and vectorise it. The gradient comes back in seconds — m / (m/s) — without being told.
core	Land on Mars in your own units	Build a mission unit system, fly a descent in it, then reproduce the Mars Climate Orbiter's lbf·s/N·s mistake and hit the ground at 139 m/s.
core	Check a formula before you run it	Dimensional analysis with no numbers: catch a wrong formula, then derive the pendulum period's form from (length/acceleration)**0.5 being a time.
core	Write a function others can call	Designing a unitful interface: a bare-float version returns 0.0 for a caller working in solar masses, and even with quantities a wrong-dimension argument is not rejected — it returns an 'unknown' dimension that only errors later, somewhere else.
core	Carry units through a whole analysis	A rotation curve through xarray → unxt → matplotlib: the computed unit km2 kg kpc / m3 looks like nonsense until dimension_of says mass, and the plot labels itself $\mathrm{M_\odot}$.
unxts.parametric	Let the type system catch a unit mistake	Q["length"](1, "s") is silently accepted; PQ["length"](1, "s") refuses.
unxts.hypothesis	Write your first property test	State a property, then see what the silence covered.
unxts.linalg	Build a heterogeneous metric	The determinant's unit falls out as the product of the diagonal.
unxts.interop.xarray	Turn unit labels into real units	xarray adds km to hours without complaint and drops the label; quantify, and it raises.
unxts.interop.matplotlib	Plot data that knows its units	Axis labels write themselves, and data in minutes lands correctly on an axis already in hours.
unxts.interop.gala	Compute in galactic units	usys["velocity"] composes kpc / Myr from base units nobody supplied.
unxts.api	Teach unxt about your own type	A generic function accepts both a Quantity and your class, unchanged.

register_ufunc and is_unit_convertible are public but appeared only in generated autodoc; both are now in the reference.

Bugs found and fixed along the way

Where	Was	Now
guides/type-checking.md	"UNXT_ENABLE_RUNTIME_TYPECHECKING=None disables checking, and is the default"	"False" is the default and disables; "None" installs the hook with no typechecker (setup_package.py:19). Two pages also contradicted each other on this.
CONTRIBUTING.md	github.com/unxt/unxt, and an Astropy dev-workflow link on docs.unxt.org	GalacticDynamics/unxt, docs.astropy.org
CONTRIBUTING.md	uv run --group test nox -s test	uv run nox -s test — the session declares its own group
reference/quantity.md (inherited from the old guide)	StaticQuantity "accepts Python scalars and NumPy arrays only, rejecting JAX arrays"	a concrete JAX array is accepted and materialised back to NumPy; only a traced value is rejected
unxts.interop.gala/docs/guide.md	a round trip "yields an equivalent unit system"	it does not — back == gu.galactic is False. gala registers a preferred unit for the derived velocity dimension (km/s); an unxt system holds only base units and composes the rest, so the preference is dropped and cannot be reconstructed.

Also updated for upstream changes

Quantity.__array__ now refuses rather than stripping units (#892) — a core sharp bit that had no home in the docs. QuantityMatrix gained unit_of/ustrip and scalar-unit uconvert (#880, #902). UnxtConverter.unit_format replaced the axisinfo_kw dict (#862). None shipped with documentation; all three are now described.

AGENTS.md and skills/unxt/SKILL.md pointed at doc paths that moved, and are fixed.

Redirects

sphinxext-rediraffe was already a docs dependency but commented out of conf.py. Now enabled, with 22 old URLs mapped; every stub and every target was checked against the built HTML.

Verification

• nox -s docs succeeds. sphinx-build -n --keep-going → 208 warnings, zero structural: 206 pre-existing py: autodoc nitpicks from docstrings this PR never touches, 2 sphinx-tippy network flakes.
• pytest docs/ → 1140 examples, all passing. The exact CI invocation (pytest README.md docs src/ tests/ --benchmark-disable -n logical --dist=loadfile) → 4271 passed, 0 failed. Whole project suite: 3845 passed, 0 failed.
• Core examples went 600 → 493 at the reorganisation, then up to 1026 with the new pages. The initial drop was deduplication, checked by diffing the API tokens exercised in executed blocks before and after rather than assumed; 88 of 107 came from index.md's quickstart re-testing what the reference pages test.

Known gaps

• No error reference. unxt has ~108 raise sites, 46 with custom messages, but most of what users actually hit surfaces as astropy's UnitConversionError. The messages people do paste into a search engine are already documented on the pages that provoke them, so the gap is findability rather than absence — a hand-written page keyed by message text would be a large artifact with exactly the drift problem noted below. Not attempted here; worth a decision rather than a default.
• Tutorials are per-topic, not per-audience. There is no "you are an astronomer / you are an ML engineer" entry path. Probably right at this size, but worth revisiting if the tutorial count grows.

Closed since this PR was opened:

• Nothing teaches how to design a unit-aware function for others to call. Now tutorials/design-a-unitful-api.md.
• unxts.hypothesis/strategies.md is long and ungrouped. Now an orienting table plus two groups. (The "736 words" figure in the original list was stale; it is 1505.)
• unxts.api/api.md hand-maintains "Example Implementations" lists that will drift. The page now points at f.methods for the authoritative set. The lists stay — they are labelled examples and carry prose a runtime query cannot.
• Derived units of a DynamicalSimUSysFlag system cannot be printed. Fixed upstream in 🐛 fix(unitsystems): derived units of scaled systems can be printed #910; usys["velocity"] now returns Unit("2.07387 m / s") and the how-to's warning is gone.

A note on the CI failure this branch hit

Four jobs failed on unxts.interop.matplotlib/guide.md with ConversionError: Failed to convert value(s) to axis units, and the rest passed. The cause was
shared global state rather than anything in the guide: it and the package index
drew with a bare plt.plot(x, y), which targets matplotlib's current axes.
Sybil runs every doc file in one process, so whichever file ran first could leave
a figure current — and when that figure's x-axis carried kpc, from the
ecosystem tutorial added here, plotting deg onto it raised. Under
-n logical --dist=loadfile the file-to-worker assignment varies with the
runner's core count, which is why it failed on some jobs and not others.

Fixed at the root: those pages now create their own fig, ax, so no page depends
on what ran before it, and the pages that make figures close them.

[Copilot]

Pull request overview

This pull request restructures unxt’s documentation (core docs/ plus the unxts.* package doc sets) to follow the Diátaxis information architecture, adds new tutorial content, and updates the docs build tooling + redirects so existing URLs continue to work.

Changes:

• Reorganized core docs into tutorials/, how-to/, reference/, explanation/ (nav “Discussion”), plus about/, including a new end-to-end beginner tutorial.
• Restructured each unxts.* package doc set to be mode-labeled while remaining a flat tree, reducing duplicated content and clarifying entry pages.
• Updated docs infrastructure: enabled sphinxext-rediraffe redirects, moved generated API docs under reference/api/, and adjusted nox + .gitignore for the relocated jupytext notebook.

Reviewed changes

Copilot reviewed 74 out of 81 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Updates documentation deep links to new Diátaxis locations.
packages/unxts.parametric/docs/type-checking.md	Retitles/reframes runtime dimension-checking how-to and repoints core links.
packages/unxts.parametric/docs/sharp-bits.md	Retitles and repoints sharp-bits link into core discussion docs.
packages/unxts.parametric/docs/quantity.md	Expands ParametricQuantity reference and integrates former “dimensions” content.
packages/unxts.parametric/docs/index.md	Refactors landing page into mode-grouped router; removes duplicated material.
packages/unxts.parametric/docs/dimensions.md	Removes page (content merged into quantity.md).
packages/unxts.parametric/docs/configuration.md	Updates core configuration link to new reference location.
packages/unxts.linalg/docs/units-matrix.md	Retitles to object-centric page name (UnitsMatrix).
packages/unxts.linalg/docs/tutorial-metric.md	Reworks tutorial into a true end-to-end lesson flow.
packages/unxts.linalg/docs/sharp-bits.md	Retitles/expands restrictions discussion and adds inv heterogeneity example.
packages/unxts.linalg/docs/quantity-matrix.md	Retitles to object-centric page name (QuantityMatrix).
packages/unxts.linalg/docs/linear-algebra.md	Retitles and clarifies operations reference page.
packages/unxts.linalg/docs/index.md	Reorders toctree and converts landing page to mode-grouped router.
packages/unxts.interop.xarray/docs/xarray-guide.md	Retitles as a how-to; moves API + limitations into dedicated pages.
packages/unxts.interop.xarray/docs/sharp-bits.md	New “sharp bits” discussion page for xarray integration limitations.
packages/unxts.interop.xarray/docs/index.md	Refactors landing page into mode-grouped router with clearer at-a-glance example.
packages/unxts.interop.xarray/docs/api.md	New API reference page documenting accessor + lower-level functions.
packages/unxts.interop.matplotlib/docs/index.md	Refactors landing page into mode-grouped router with updated headings.
packages/unxts.interop.matplotlib/docs/guide.md	Retitles guide as a how-to and normalizes “See also”/API link text.
packages/unxts.interop.matplotlib/docs/api.md	Normalizes API page title.
packages/unxts.interop.gala/docs/index.md	Refactors landing page into mode-grouped router and updates deep links.
packages/unxts.interop.gala/docs/guide.md	Retitles guide as a how-to; updates “See also” links.
packages/unxts.interop.gala/docs/api.md	Normalizes API page title and updates deep links.
packages/unxts.hypothesis/docs/testing-guide.md	Retitles as a how-to and expands “See also” navigation.
packages/unxts.hypothesis/docs/strategies.md	New strategies reference page extracted from index content.
packages/unxts.hypothesis/docs/recipes.md	New how-to page for composing hypothesis strategies.
packages/unxts.api/docs/why-abstract-dispatch.md	New discussion page explaining the abstract dispatch split.
packages/unxts.api/docs/index.md	Refactors landing page into mode-grouped router; adds high-level “at a glance”.
packages/unxts.api/docs/extending.md	Retitles and improves structure for how to extend via dispatch.
packages/unxts.api/docs/api.md	Normalizes API page title and adds intro framing.
noxfile.py	Updates docs build (jupytext path) and API doc generation output directory.
docs/tutorials/index.md	New tutorials section landing page.
docs/tutorials/first-quantity.md	New beginner tutorial with executed, end-to-end unitful JAX workflow.
docs/reference/unitsystems.md	New unit systems reference page (replacing mixed-mode guide content).
docs/reference/units.md	New units reference page (replacing mixed-mode guide content).
docs/reference/quantity.md	New quantity reference page consolidating class/method surface.
docs/reference/index.md	New reference section landing page and routing.
docs/reference/glossary.md	Moves glossary under reference and fixes intra-doc links.
docs/reference/dimensions.md	Updates parametric-quantity link target and “See also”/API role usage.
docs/reference/dataclassish.md	Retitles/reframes dataclassish behavior as reference; adds see-also links.
docs/reference/configuration.md	New configuration reference (options, defaults, and file keys).
docs/reference/api/unitsystems.md	Moves API stub under reference/api/.
docs/reference/api/units.md	Moves API stub under reference/api/.
docs/reference/api/quantity.md	Moves API stub under reference/api/ and keeps exclude-members list.
docs/reference/api/index.md	New API index under reference, with submodule toctree.
docs/reference/api/experimental.md	Moves API stub under reference/api/.
docs/reference/api/dims.md	Moves API stub under reference/api/.
docs/interop/astropy.md	Removes legacy interop page (content moved to new how-to).
docs/how-to/work-in-natural-units.md	Retitles as how-to, adds pointer to new unit-systems reference.
docs/how-to/use-jax-functions.md	New how-to consolidating quax/quaxed/JAX transform usage patterns.
docs/how-to/optimize-performance.md	Retitles/moves performance notebook source to how-to section.
docs/how-to/migrate-to-v2.md	Retitles as how-to and links to new discussion rationale page.
docs/how-to/interoperate-with-astropy.md	New how-to replacing old interop page and documenting jit pitfalls.
docs/how-to/install.md	New installation how-to.
docs/how-to/index.md	New how-to section landing page with curated guide grouping.
docs/how-to/define-a-unit-system.md	New how-to for defining custom unit system subclasses.
docs/how-to/convert-units.md	New how-to for uconvert/ustrip/uconvert_value.
docs/how-to/control-display.md	New how-to for display configuration usage patterns.
docs/how-to/check-types-at-runtime.md	New how-to clarifying runtime type-checking defaults and usage.
docs/guides/units_and_systems.md	Removes mixed-mode legacy guide (replaced by reference/how-to pages).
docs/guides/type-checking.md	Removes mixed-mode legacy guide (replaced by how-to).
docs/guides/configuration.md	Removes mixed-mode legacy guide (replaced by reference/how-to).
docs/explanation/why-quantity-is-non-parametric.md	New discussion page consolidating rationale behind v2 default.
docs/explanation/sharp-bits.md	New discussion page for inherent JAX/units sharp edges.
docs/explanation/index.md	New discussion section landing page.
docs/explanation/equality-and-equivalence.md	New discussion page distinguishing == vs equivalent.
docs/explanation/api-conventions.md	Retitles and reframes conventions as discussion; adds see-also links.
docs/dev.md	Removes legacy developer page (merged into about/contributing).
docs/contributing.md	Removes legacy contributing page (replaced by include-based about page).
docs/conf.py	Enables rediraffe, adds redirect map, and updates exclude patterns/source suffixes.
docs/about/index.md	New about section landing page (citation + ecosystem + navigation).
docs/about/contributing.md	New about page including root CONTRIBUTING plus docs-build + Diátaxis guidance.
CONTRIBUTING.md	Fixes repo URL + dev workflow link + updates test command; adds Diátaxis pointer.
audit/summary.md	Adds audit summary of restructure decisions, verification, and remaining gaps.
audit/package-migration-map.md	Adds package-doc-set migration map and rationale for flat structure.
audit/migration-map.md	Adds core-doc migration plan/map (as documentation/audit artifact).
.gitignore	Updates ignored jupytext-generated notebook path to new location.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.80%. Comparing base (62da772) to head (3ed9ff2).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #909      +/-   ##
==========================================
- Coverage   99.80%   99.80%   -0.01%     
==========================================
  Files          84       82       -2     
  Lines        4019     4013       -6     
  Branches      314      314              
==========================================
- Hits         4011     4005       -6     
  Misses          4        4              
  Partials        4        4              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 88 out of 95 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 88 out of 95 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 88 out of 95 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

docs/reference/dataclassish.md:5

• The rewritten lead sentence (line 3) now states that every unxt type is an Equinox module / Python dataclass that works with dataclassish. The following sentence (line 5) — carried over from the previous version of this page — repeats the same fact almost verbatim, so the two are now redundant. Consider dropping the duplicated sentence.

[Copilot]

Pull request overview

Copilot reviewed 90 out of 97 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 91 out of 98 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

docs/how-to/check-types-at-runtime.md:108

• The link text "Dimension annotations for type checking" is stale. The target page was retitled to "How to check dimensions at runtime" and its section is now "Annotate with a dimensioned type" (see packages/unxts.parametric/docs/type-checking.md:1,10), so this link text no longer matches any heading on the linked page. Consider updating the link text to match the page's current title.

Annotations on the default `Quantity` constrain dtype and shape but **not** dimension: `Quantity["length"]` is `Quantity`, and the subscript does nothing. To have an argument's dimension checked, use `ParametricQuantity` from the separate [`unxts.parametric`](../packages/unxts.parametric/index) package, which encodes the dimension in its type — see [Dimension annotations for type checking](../packages/unxts.parametric/type-checking).