spatialscape 0.3.0__tar.gz

spatialscape-0.3.0/.gitignore

@@ -0,0 +1,28 @@
+node_modules/
+dist/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+app/test-results/
+app/playwright-report/
+.DS_Store
+.npmrc
+.claude/
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+app/tsconfig.tsbuildinfo
+# real-data bundles and their source exports stay local (large, derived from cluster data)
+examples/*/
+!examples/synthetic/
+!examples/synthetic-src/
+!examples/scripts/
+!examples/palettes/
+# viewer build copied into the package by python/scripts/bundle_app.py
+python/src/spatialscape/_app/
+python/dist/
+# per-machine registry overlay used by the vite dev server
+app/public/datasets.local.json

spatialscape-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Totty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spatialscape-0.3.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: spatialscape
+Version: 0.3.0
+Summary: Build static spatialscape viewer bundles from AnnData / SpatialData
+Project-URL: Homepage, https://mictott.github.io/spatialscape/docs/
+Project-URL: Documentation, https://mictott.github.io/spatialscape/docs/
+Project-URL: Repository, https://github.com/mictott/spatialscape
+Project-URL: Issues, https://github.com/mictott/spatialscape/issues
+Project-URL: Changelog, https://github.com/mictott/spatialscape/blob/main/CHANGELOG.md
+Author-email: Michael Totty <mictott@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: deck.gl,single-cell,spatial-transcriptomics,visium,visualization,xenium,zarr
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Requires-Dist: anndata>=0.12
+Requires-Dist: imageio>=2.34
+Requires-Dist: numcodecs>=0.15
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.0
+Requires-Dist: pillow>=10
+Requires-Dist: pyarrow>=15
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6
+Requires-Dist: scikit-image>=0.22
+Requires-Dist: scipy>=1.11
+Requires-Dist: tifffile>=2024.1
+Requires-Dist: typer>=0.12
+Requires-Dist: zarr>=3.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: h5py>=3.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: spatialdata
+Requires-Dist: spatialdata>=0.4; extra == 'spatialdata'
+Provides-Extra: tracks
+Requires-Dist: pybigwig>=0.3.18; extra == 'tracks'
+Description-Content-Type: text/markdown
+
+# spatialscape (Python)
+
+The command-line tool behind **spatialscape**, a static, reactive browser for spatial transcriptomics and
+snRNA-seq. It turns a saved R object (`SpatialExperiment` / `SingleCellExperiment` as `.rds` or `.rda`, parsed in
+Python) or AnnData / SpatialData files into viewer bundles (sharded Zarr v3 expression, observation arrays in
+microns, OME-Zarr images, domain outlines, cell polygons), and ships the viewer itself so you can open them locally
+or publish them as a website.
+
+```bash
+pip install spatialscape
+spatialscape init analysis/spe_dlpfc.rds --id dlpfc    # writes dlpfc.yaml, a menu of what the data contains
+# edit dlpfc.yaml: keep the annotations you want, name them, pick colors and the opening gene
+spatialscape build dlpfc.yaml                          # -> bundles/dlpfc; rerun after any edit
+spatialscape serve bundles --open                      # viewer + data at http://127.0.0.1:8787/
+spatialscape site build bundles -o site                # folder to upload to any static host
+```
+
+`sscape` is a short alias for the same command. Documentation: https://mictott.github.io/spatialscape/docs/
+Source and issues: https://github.com/MicTott/spatialscape

spatialscape-0.3.0/README.md

@@ -0,0 +1,19 @@
+# spatialscape (Python)
+
+The command-line tool behind **spatialscape**, a static, reactive browser for spatial transcriptomics and
+snRNA-seq. It turns a saved R object (`SpatialExperiment` / `SingleCellExperiment` as `.rds` or `.rda`, parsed in
+Python) or AnnData / SpatialData files into viewer bundles (sharded Zarr v3 expression, observation arrays in
+microns, OME-Zarr images, domain outlines, cell polygons), and ships the viewer itself so you can open them locally
+or publish them as a website.
+
+```bash
+pip install spatialscape
+spatialscape init analysis/spe_dlpfc.rds --id dlpfc    # writes dlpfc.yaml, a menu of what the data contains
+# edit dlpfc.yaml: keep the annotations you want, name them, pick colors and the opening gene
+spatialscape build dlpfc.yaml                          # -> bundles/dlpfc; rerun after any edit
+spatialscape serve bundles --open                      # viewer + data at http://127.0.0.1:8787/
+spatialscape site build bundles -o site                # folder to upload to any static host
+```
+
+`sscape` is a short alias for the same command. Documentation: https://mictott.github.io/spatialscape/docs/
+Source and issues: https://github.com/MicTott/spatialscape

spatialscape-0.3.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spatialscape"
+dynamic = ["version"]
+description = "Build static spatialscape viewer bundles from AnnData / SpatialData"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Michael Totty", email = "mictott@gmail.com" }]
+keywords = ["spatial-transcriptomics", "visium", "xenium", "single-cell", "visualization", "zarr", "deck.gl"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Topic :: Scientific/Engineering :: Visualization",
+  "Environment :: Web Environment",
+]
+dependencies = [
+  "anndata>=0.12",
+  "zarr>=3.0",
+  "numcodecs>=0.15",
+  "numpy>=1.26",
+  "scipy>=1.11",
+  "pandas>=2.0",
+  "pyarrow>=15",
+  "typer>=0.12",
+  "pydantic>=2.6",
+  "pyyaml>=6",
+  "imageio>=2.34",
+  "tifffile>=2024.1",
+  "scikit-image>=0.22",
+  "pillow>=10",
+]
+
+[project.urls]
+Homepage = "https://mictott.github.io/spatialscape/docs/"
+Documentation = "https://mictott.github.io/spatialscape/docs/"
+Repository = "https://github.com/mictott/spatialscape"
+Issues = "https://github.com/mictott/spatialscape/issues"
+Changelog = "https://github.com/mictott/spatialscape/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+spatialdata = ["spatialdata>=0.4"]
+tracks = ["pyBigWig>=0.3.18"]
+dev = ["pytest>=8", "ruff>=0.5", "h5py>=3.10", "build>=1.2"]
+
+[project.scripts]
+spatialscape = "spatialscape.cli:main"
+sscape = "spatialscape.cli:main"
+
+[tool.hatch.version]
+path = "src/spatialscape/__init__.py"
+
+[tool.hatch.build]
+# the viewer build is generated (python/scripts/bundle_app.py) and gitignored, so list it explicitly
+artifacts = ["src/spatialscape/_app/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spatialscape"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "PIE", "C4", "RUF"]
+ignore = ["E501", "B008", "SIM108", "RUF012", "RUF005"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

spatialscape-0.3.0/scripts/bundle_app.py

@@ -0,0 +1,39 @@
+"""Copy the built viewer (app/dist) into the Python package so the wheel ships it.
+
+    npm run build && python python/scripts/bundle_app.py
+
+Only index.html and assets/ are copied: no source maps, no registry, no site drafts. The copy lives at
+src/spatialscape/_app (gitignored) and is picked up by `spatialscape serve` and `spatialscape site build`.
+"""
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+DIST = ROOT / "app" / "dist"
+DEST = ROOT / "python" / "src" / "spatialscape" / "_app"
+
+
+def main() -> None:
+    if not (DIST / "index.html").exists():
+        sys.exit(f"{DIST} has no build; run `npm run build` first")
+    if DEST.exists():
+        shutil.rmtree(DEST)
+    (DEST / "assets").mkdir(parents=True)
+    shutil.copy2(DIST / "index.html", DEST / "index.html")
+    if (DIST / "favicon.svg").exists():
+        shutil.copy2(DIST / "favicon.svg", DEST / "favicon.svg")
+    n = 0
+    for f in (DIST / "assets").iterdir():
+        if f.suffix == ".map":
+            continue
+        shutil.copy2(f, DEST / "assets" / f.name)
+        n += 1
+    size = sum(p.stat().st_size for p in DEST.rglob("*") if p.is_file())
+    print(f"packaged viewer: index.html + {n} assets, {size / 1e6:.1f} MB -> {DEST}")
+
+
+if __name__ == "__main__":
+    main()

spatialscape-0.3.0/scripts/gen_brand.py

@@ -0,0 +1,83 @@
+"""The spatialscape mark: a tissue section made of spots whose colored domains roll like hills.
+
+    python/.venv/bin/python python/scripts/gen_brand.py
+
+Writes docs/public/brand/{mark,banner-dark,banner-light}.svg (also copied to docs/public/logo.svg and app/public/favicon.svg).
+"""
+import math
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+out = Path(sys.argv[1]) if len(sys.argv) > 1 else ROOT / "docs" / "public" / "brand"
+out.mkdir(parents=True, exist_ok=True)
+CX = CY = 128
+R_DISC = 118
+R_FILL = 104          # dots live inside this radius
+PITCH = 15.5
+DOT = 5.6
+DISC = "#141a26"
+SKY = "#2a3449"
+SUN = "#ff8a5b"
+BANDS = ["#f5d324", "#35c46a", "#3d7fe0", "#8b5cf6"]  # yellow, green, blue, violet from top to bottom
+
+def curve(k, x):
+    """boundary k between band k-1 and band k, as y(x): a hill rising on the left, strata following it"""
+    t = (x - CX) / R_FILL
+    hill = -26 * math.exp(-((t + 0.35) / 0.55) ** 2) + 10 * math.sin(t * 2.2 + 2.4)   # one crest left, a dip under the sun
+    base = [112, 146, 178, 206][k]
+    follow = [1.0, 0.75, 0.5, 0.3][k]
+    return base + follow * hill + 3 * math.sin(t * 6.1 + k * 1.7)
+
+
+def band_of(x, y):
+    for k in range(4):
+        if y < curve(k, x):
+            return k - 1      # -1 = sky
+    return 3
+
+def dots():
+    rows = int(2 * R_FILL / (PITCH * math.sqrt(3) / 2)) + 3
+    out = []
+    for j in range(-rows, rows + 1):
+        y = CY + j * PITCH * math.sqrt(3) / 2
+        off = PITCH / 2 if j % 2 else 0
+        cols = int(2 * R_FILL / PITCH) + 3
+        for i in range(-cols, cols + 1):
+            x = CX + i * PITCH + off
+            if math.hypot(x - CX, y - CY) > R_FILL:
+                continue
+            out.append((x, y))
+    return out
+
+def mark_svg():
+    parts = [f'<circle cx="{CX}" cy="{CY}" r="{R_DISC}" fill="{DISC}"/>']
+    sun = (CX + 52, CY - 58)
+    parts.append(f'<circle cx="{sun[0]}" cy="{sun[1]}" r="13" fill="{SUN}"/>')
+    for x, y in dots():
+        if math.hypot(x - sun[0], y - sun[1]) < 20:
+            continue
+        b = band_of(x, y)
+        if b < 0:
+            parts.append(f'<circle cx="{x:.1f}" cy="{y:.1f}" r="{DOT*0.55:.1f}" fill="{SKY}"/>')
+        else:
+            parts.append(f'<circle cx="{x:.1f}" cy="{y:.1f}" r="{DOT}" fill="{BANDS[b]}"/>')
+    return "\n".join(parts)
+
+inner = mark_svg()
+mark = f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256">\n{inner}\n</svg>\n'
+(out / "mark.svg").write_text(mark)
+
+def banner(fill, name):
+    txt = (f'<text x="76" y="63" font-family="Inter, \'Helvetica Neue\', Helvetica, Arial, sans-serif" font-size="46" '
+           f'font-weight="600" letter-spacing="-1.2" fill="{fill}" textLength="286" lengthAdjust="spacingAndGlyphs">spatialscape</text>')
+    svg = (f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 372 96" width="372" height="96">\n'
+           f'<g transform="translate(8 16) scale(0.25)">\n{inner}\n</g>\n{txt}\n</svg>\n')
+    (out / name).write_text(svg)
+
+banner("#e6edf3", "banner-dark.svg")
+banner("#1f2328", "banner-light.svg")
+
+for copy in (ROOT / "docs" / "public" / "logo.svg", ROOT / "app" / "public" / "favicon.svg"):
+    copy.write_text(mark)
+print("wrote", sorted(p.name for p in out.iterdir()))

spatialscape-0.3.0/scripts/gen_cli_docs.py

@@ -0,0 +1,247 @@
+"""Generate the CLI reference pages for the docs site from the Typer app itself.
+
+    python/.venv/bin/python python/scripts/gen_cli_docs.py
+
+Writes docs/reference/cli/index.md, one page per command, and sidebar.json used by the VitePress config.
+Help strings in spatialscape/cli.py are the single source of truth; examples live in EXAMPLES below.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import typer.main
+
+from spatialscape.cli import app
+
+ROOT = Path(__file__).resolve().parents[2]
+OUT = ROOT / "docs" / "reference" / "cli"
+
+EXAMPLES: dict[str, list[tuple[str, str]]] = {
+    "init": [
+        ("A SpatialExperiment saved from R (one sample per sample_id)", 'spatialscape init analysis/spe_visium.rds --id dlpfc --name "Human DLPFC"'),
+        ("Xenium donors in sibling folders", 'spatialscape init "xenium/*/adata.zarr" --platform xenium --id amygdala --name "Human amygdala"'),
+        ("A spatial object and the snRNA-seq reference behind its labels, one dataset", "spatialscape init analysis/spe_visium.rds analysis/sce_snrnaseq.rds --id dlpfc"),
+    ],
+    "build": [
+        ("Build, or update after editing the yaml (default output: `bundles/<id>` next to it)", "spatialscape build dlpfc.yaml"),
+        ("See what would be rebuilt and why, without writing anything", "spatialscape build dlpfc.yaml --dry-run"),
+        ("For GitHub Pages or other hosts without Range support", "spatialscape build dlpfc.yaml --no-shard"),
+        ("Rebuild everything", "spatialscape build dlpfc.yaml --force"),
+    ],
+    "serve": [
+        ("Open everything under a folder in the viewer", "spatialscape serve bundles --open"),
+        ("Reachable from another machine on the network", "spatialscape serve bundles --host 0.0.0.0 --port 8787"),
+        ("Preview a site written by `site build`", "spatialscape serve site"),
+    ],
+    "site init": [
+        ("List two datasets and start a gallery yaml", 'spatialscape site init dlpfc.yaml amygdala.yaml --title "Our lab\'s spatial data"'),
+        ("Pick up every dataset yaml and bundle in the current folder", "spatialscape site init"),
+    ],
+    "site build": [
+        ("The gallery described in site.yaml (default output: site/ next to it)", "spatialscape site build site.yaml"),
+        ("One dataset, no settings: viewer + bundles from a folder", "spatialscape site build bundles -o site"),
+        ("Local preview of large bundles without copying them", "spatialscape site build site.yaml --link && spatialscape serve site"),
+    ],
+    "inspect": [
+        ("A SpatialExperiment saved from R", "spatialscape inspect analysis/spe_visium.rds"),
+        ("An h5ad written from R", "spatialscape inspect Br2743.h5ad"),
+        ("A SpatialData store with several tables", "spatialscape inspect store.zarr --table cells"),
+    ],
+    "validate": [
+        ("Before upload", "spatialscape validate bundles/dlpfc"),
+        ("After upload", "spatialscape validate https://data.example.org/dlpfc"),
+    ],
+    "outlines": [
+        ("All spatial samples, all categorical fields", "spatialscape outlines dlpfc.yaml"),
+        ("Finer outlines for one Xenium donor", "spatialscape outlines amygdala.yaml --sample xen_Br9280 --field domain --smooth-um 80 --min-feature-um 150"),
+    ],
+    "thumbnails": [("Lead with a particular section", "spatialscape thumbnails bundles/dlpfc --hero vis_Br8325")],
+    "synth": [("Make inputs, build them, serve them", "spatialscape synth demo-src && spatialscape build demo-src/dataset.yaml && spatialscape serve demo-src/bundles --open")],
+}
+RELATED: dict[str, list[str]] = {
+    "init": ["build", "inspect"],
+    "build": ["serve", "validate", "site build"],
+    "serve": ["build", "site build"],
+    "site init": ["site build"],
+    "site build": ["site init", "serve", "build"],
+    "inspect": ["init"],
+    "validate": ["build", "serve"],
+    "outlines": ["build"],
+    "thumbnails": ["build"],
+    "synth": ["build"],
+}
+GUIDE_LINKS: dict[str, tuple[str, str]] = {
+    "init": ("Writing dataset.yaml", "/guide/dataset-yaml"),
+    "build": ("Building and validating", "/guide/building"),
+    "serve": ("Getting started", "/guide/getting-started"),
+    "site init": ("The gallery: site.yaml", "/guide/registry"),
+    "site build": ("Publish your own site", "/guide/publish"),
+    "inspect": ("Inputs: what the CLI reads", "/guide/preparing-data"),
+    "validate": ("Hosting", "/guide/hosting"),
+    "outlines": ("Using the viewer: outlines", "/guide/viewer#outlines"),
+    "thumbnails": ("The gallery: site.yaml", "/guide/registry"),
+    "synth": ("Getting started", "/guide/getting-started#try-it-in-two-minutes"),
+}
+
+
+def is_arg(p) -> bool:
+    return p.param_type_name == "argument"
+
+
+def is_opt(p) -> bool:
+    return p.param_type_name == "option"
+
+
+def md_inline(s: str) -> str:
+    """Help strings use backticks already; just escape table pipes."""
+    return (s or "").replace("|", "\\|").replace("\n", " ")
+
+
+def type_name(p) -> str:
+    t = p.type
+    if is_opt(p) and p.is_flag:
+        return "flag"
+    name = getattr(t, "name", str(t)).upper()
+    if name in ("TEXT", "STR", "STRING"):
+        name = "text"
+    elif name in ("INTEGER",):
+        name = "int"
+    elif name in ("FLOAT",):
+        name = "float"
+    elif name in ("PATH",):
+        name = "path"
+    else:
+        name = name.lower()
+    return name + (", repeatable" if p.multiple else "")
+
+
+def default_str(p) -> str:
+    if p.required:
+        return "*required*"
+    d = p.default
+    if is_opt(p) and p.is_flag:
+        return "`off`" if not d else "`on`"
+    if d is None or d == () or d == []:
+        return "—"
+    if callable(d):
+        return "—"
+    return f"`{d}`"
+
+
+def usage(cmd_name: str, cmd) -> str:
+    parts = [f"spatialscape {cmd_name}"]
+    for p in cmd.params:
+        if is_arg(p):
+            nm = p.human_readable_name.upper()
+            parts.append(f"<{nm}>" + ("..." if p.nargs == -1 else "") if p.required else f"[{nm}]")
+    if any(is_opt(p) for p in cmd.params):
+        parts.append("[OPTIONS]")
+    return " ".join(parts)
+
+
+def page(cmd_name: str, cmd) -> str:
+    doc = (cmd.help or "").strip()
+    summary, _, rest = doc.partition("\n\n")
+    rest = re.sub(r"\n(?!\n)", " ", rest).strip()
+    args = [p for p in cmd.params if is_arg(p)]
+    opts = [p for p in cmd.params if is_opt(p) and p.name != "help"]
+    out = [f"# `spatialscape {cmd_name}`", "", summary, ""]
+    if rest:
+        out += [rest, ""]
+    out += ["## Usage", "", "```bash", usage(cmd_name, cmd), "```", ""]
+    if args:
+        out += ["## Arguments", "", "| Argument | Type | Default | Description |", "|---|---|---|---|"]
+        for p in args:
+            out.append(f"| `{p.human_readable_name.upper()}` | {type_name(p)} | {default_str(p)} | {md_inline(getattr(p, 'help', '') or '')} |")
+        out.append("")
+    if opts:
+        out += ["## Options", "", "| Option | Type | Default | Description |", "|---|---|---|---|"]
+        for p in opts:
+            names = ", ".join(f"`{o}`" for o in (p.opts + p.secondary_opts))
+            out.append(f"| {names} | {type_name(p)} | {default_str(p)} | {md_inline(p.help or '')} |")
+        out.append("")
+    ex = EXAMPLES.get(cmd_name, [])
+    if ex:
+        out += ["## Examples", ""]
+        for title, code in ex:
+            if "`" not in title:
+                title = title.replace("<", "&lt;").replace(">", "&gt;")
+            out += [f"**{title}**", "", "```bash", code, "```", ""]
+    rel = RELATED.get(cmd_name, [])
+    g = GUIDE_LINKS.get(cmd_name)
+    if rel or g:
+        out += ["## See also", ""]
+        for r in rel:
+            out.append(f"- [`spatialscape {r}`](./{r.replace(' ', '-')})")
+        if g:
+            out.append(f"- Guide: [{g[0]}]({g[1]})")
+        out.append("")
+    return "\n".join(out)
+
+
+def main() -> None:
+    group = typer.main.get_command(app)
+    assert hasattr(group, "commands"), "expected a command group"
+    OUT.mkdir(parents=True, exist_ok=True)
+    commands: dict[str, object] = {}
+    for n, cmd in group.commands.items():
+        if hasattr(cmd, "commands"):  # nested group such as `site`
+            for sub, subcmd in cmd.commands.items():
+                commands[f"{n} {sub}"] = subcmd
+        else:
+            commands[n] = cmd
+    names = [n for n in EXAMPLES if n in commands]  # documented order
+    names += [n for n in commands if n not in names]
+    rows = []
+    sidebar = []
+    for n in names:
+        cmd = commands[n]
+        slug = n.replace(" ", "-")
+        (OUT / f"{slug}.md").write_text(page(n, cmd))
+        summary = (cmd.help or "").strip().partition("\n\n")[0]
+        rows.append(f"| [`{n}`](./{slug}) | {md_inline(summary)} |")
+        sidebar.append({"text": n, "link": f"/reference/cli/{slug}"})
+    index = [
+        "# CLI commands",
+        "",
+        "Four commands cover the normal path: `init` writes a dataset yaml from your data, `build` turns it into a bundle (and updates the bundle after every edit), `serve` opens it, `site build` writes the folder to publish. Every command is also available as `sscape <command>`, and `spatialscape <command> --help` prints the same information as these pages.",
+        "",
+        "```bash",
+        "pip install spatialscape",
+        "spatialscape --help",
+        "```",
+        "",
+        "| Command | Purpose |",
+        "|---|---|",
+        *rows,
+        "",
+        "## Typical sequence",
+        "",
+        "```bash",
+        "spatialscape init analysis/spe_visium.rds --id my_atlas     # writes my_atlas.yaml, a menu of the data",
+        "# edit my_atlas.yaml: annotations, names, colors, the opening gene",
+        "spatialscape build my_atlas.yaml                            # -> bundles/my_atlas; rerun after any edit",
+        "spatialscape serve bundles --open",
+        "spatialscape site init my_atlas.yaml && spatialscape site build site.yaml   # only for a gallery with settings",
+        "# ... upload site/ (or the bundles alone) ...",
+        "spatialscape validate https://data.example.org/my_atlas",
+        "```",
+        "",
+        "## Exit codes",
+        "",
+        "`build` and `validate` exit with status 1 when validation reports problems, so they can gate a deployment script. Every other command exits 0 on success and prints a one-line error otherwise (`SPATIALSCAPE_DEBUG=1` shows the traceback).",
+        "",
+        "::: tip Generated reference",
+        "These pages are generated from the CLI's own help text by `python/scripts/gen_cli_docs.py`. If a page and `--help` ever disagree, `--help` is right and the generator needs re-running.",
+        ":::",
+        "",
+    ]
+    (OUT / "index.md").write_text("\n".join(index))
+    (OUT / "sidebar.json").write_text(json.dumps(sidebar, indent=2))
+    print(f"wrote {len(names)} command pages to {OUT}")
+
+
+if __name__ == "__main__":
+    main()

spatialscape-0.3.0/src/spatialscape/__init__.py

@@ -0,0 +1,13 @@
+"""spatialscape: build static spatialscape viewer bundles, or show an object from the session you are in."""
+
+from importlib import import_module
+
+__version__ = "0.3.0"
+
+__all__ = ["Session", "show", "stop"]
+
+
+def __getattr__(name: str):  # lazy: the CLI must not pay for importing the build stack at startup
+    if name in ("show", "stop", "Session"):
+        return getattr(import_module(".session", __name__), name)
+    raise AttributeError(name)