Align Python/Rust parity and publish examples site

.github/workflows/deploy.yml

@@ -30,13 +30,28 @@ jobs:
       - uses: actions/checkout@v4
       - name: Setup Pages
         uses: actions/configure-pages@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
       - uses: actions/setup-node@v4
         with:
           node-version: 18.x
       - name: Install MyST Markdown
         run: npm install -g mystmd
+      - name: Install Python dependencies for examples
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pyyaml jsonschema requests biopython pydantic opentelemetry-sdk
+      - name: Build examples site
+        env:
+          MPLBACKEND: Agg
+        run: python docs/examples/build_examples.py
       - name: Build HTML Assets
         run: myst build --html
+      - name: Copy examples into Pages artifact
+        run: |
+          mkdir -p _build/html/examples
+          cp -r docs/examples/site/. _build/html/examples/
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

.gitignore

@@ -1,5 +1,7 @@
 .vscode/
 docs/_build/
+_build/
+.mplconfig/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "seqspec"
+version = "0.4.0"
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/pachterlab/seqspec"
+description = "Sequencing specification tools (Rust core + PyO3 bindings)"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[lib]
+name = "seqspec"
+crate-type = ["rlib", "cdylib"]
+
+[dependencies]
+anyhow = "1"
+clap = { version = "4.5.46", features = ["derive", "env"] }
+jsonschema = "0.33.0"
+pyo3 = { version = "0.25", optional = true, features = ["extension-module", "abi3-py312"] }
+# pythonize = "0.25.0"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+serde_yaml = "0.9"
+thiserror = "1"
+reqwest = { version = "0.12", features = ["blocking", "rustls-tls"] }
+flate2 = "1"
+toml = "0.8"
+
+
+[features]
+default = []
+python-binding = ["pyo3"]          # enable PyO3 only when building Python wheels

README.md

@@ -16,6 +16,18 @@ We have multiple tutorials to get you up and running with `seqspec`:
 
 2. Understand how to [manipulate `seqspec` files](docs/USING_SEQSPEC.ipynb) using the `seqspec` command-line tool.
 
+## Current release
+
+`seqspec 0.4.0` keeps the Python and Rust implementations aligned around the same core command set.
+
+- `seqspec upgrade` upgrades `0.3.0` specs to `0.4.0` in both implementations.
+- `seqspec` loads gzipped specs directly, so `.yaml.gz` works anywhere a spec path is accepted.
+- `seqspec auth` manages host-matched auth profiles for remote resources, and `seqspec check` / `seqspec onlist` can use them with `--auth-profile`.
+- `seqspec check` now emits warnings for valid but risky geometry, such as reads that cover the same declared regions.
+- `seqspec onlist -s region-type` now errors when the same region type appears across multiple reads, so ambiguous joins are explicit.
+- `seqspec print -f seqspec-html` writes a self-contained HTML view of the library and reads.
+- `seqspec build` is deprecated.
+
 ## Citation
 
 The `seqspec` format and tool are described in this [publication](https://doi.org/10.1093/bioinformatics/btae168). If you use `seqspec` please cite
@@ -29,11 +41,35 @@ Ali Sina Booeshaghi, Xi Chen, Lior Pachter, A machine-readable specification for
 ## Documentation
 
 - [Install `seqspec`: `docs/INSTALLATION.md`](docs/INSTALLATION.md)
-- [Learn about the `seqspec` file format: `docs/DOCUMENTATION.md`](docs/SEQSPEC_FILE.md)
-- [Learn about the `seqspec` tool: `docs/DOCUMENTATION.md`](docs/SEQSPEC_TOOL.md)
-- [Learn about the `seqspec` specification : `docs/SPECIFICATION.md`](docs/SPECIFICATION.md)
-- [Write a `seqspec`: `docs/TUTORIAL.md`](docs/TUTORIAL.md)
-- [View example `seqspec` files: `https://www.sina.bio/seqspec-builder/assays.html`](https://www.sina.bio/seqspec-builder/assays.html)
+- [Learn about the `seqspec` file format: `docs/SEQSPEC_FILE.md`](docs/SEQSPEC_FILE.md)
+- [Learn about the `seqspec` tool: `docs/SEQSPEC_TOOL.md`](docs/SEQSPEC_TOOL.md)
+- [Learn about the `seqspec` specification: `docs/SPECIFICATION.md`](docs/SPECIFICATION.md)
+- [Write a `seqspec` from a simple example: `docs/TUTORIAL_SIMPLE.md`](docs/TUTORIAL_SIMPLE.md)
+- [Write a `seqspec` from a template: `docs/TUTORIAL_FROM_TEMPLATE.md`](docs/TUTORIAL_FROM_TEMPLATE.md)
+- [Write a more complex `seqspec`: `docs/TUTORIAL_COMPLEX.md`](docs/TUTORIAL_COMPLEX.md)
+- [Browse the generated example site: `docs/examples/site/assays.html`](docs/examples/site/assays.html)
 - [Contribute a `seqspec` : `docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md)
 - [Watch a YouTube video about `seqspec`](https://youtu.be/NSj6Vpzy8tU)
 - [Read the manuscript that describes `seqspec`](https://doi.org/10.1093/bioinformatics/btae168)
+
+## Rust implementation
+
+- [x] auth : Manage remote authentication profiles.
+- build : Deprecated in both CLIs.
+- [x] check : Validate seqspec file against specification (verify check)
+- [x] find : Find objects in seqspec file
+- [x] file : List files present in seqspec file
+- [x] format : Autoformat seqspec file
+- [x] index : Identify position of elements in seqspec file
+- [x] info : Get information from seqspec file
+- [x] init : Generate a new empty seqspec file
+- [x] insert : Insert regions or reads into an existing spec (TODO: move Input structs to models)
+- [x] methods : Convert seqspec file into methods section
+- [x] modify : Modify attributes of various elements in seqspec file
+- [x] onlist : Get onlist file for elements in seqspec file
+- [x] print : Display the sequence and/or library structure from seqspec file
+- [x] split : Split seqspec file by modality
+- [x] upgrade : Upgrade seqspec file to current version
+- [x] version: Get seqspec tool version and seqspec file version
+
+The standalone Rust CLI supports `library-ascii`, `seqspec-ascii`, and `seqspec-html` in `seqspec print`. `seqspec-png` remains Python-only for now.

docs/CHANGELOG.md

@@ -7,6 +7,32 @@ authors:
 
 # Changelog
 
+## [0.4.1] - Unreleased
+
+### Added
+
+- `seqspec auth` in Python and Rust with `init`, `path`, `list`, and `resolve` subcommands.
+- `seqspec print -f seqspec-html`, a self-contained HTML view that shows the library molecule, reads, and nested region metadata.
+- Additional parity tests for Python and Rust command behavior.
+- `seqspec check` now emits warning diagnostics for overlapping read geometry, with guidance to use `seqspec index --no-overlap` when needed.
+- A generated examples site under `docs/examples/site`, with rendered assay reports, read templates, region templates, and a searchable assay catalog.
+
+### Changed
+
+- `seqspec upgrade` now upgrades `0.3.0` specs to `0.4.0` in both implementations.
+- Python and Rust now share the same core command surface for `auth`, `check`, `find`, `file`, `format`, `index`, `info`, `init`, `insert`, `methods`, `modify`, `onlist`, `print`, `split`, `upgrade`, and `version`.
+- `seqspec build` is deprecated in both CLIs and remains as a compatibility stub.
+- Older specs are loaded more permissively before upgrade, which makes `0.2.x` and `0.3.x` specs easier to normalize.
+- `seqspec onlist -s region-type` now errors when matches span multiple reads in a modality. Use `-s read` or `-s region` to disambiguate.
+- The maintained examples now live under `docs/examples/assays`, `docs/examples/reads`, and `docs/examples/regions`, with one colocated `docs/examples/build_examples.py` script to normalize YAML, write the manifest, and regenerate the site.
+- GitHub Pages now publishes the generated examples site under `/examples/` alongside the main MyST documentation site.
+
+### Fixed
+
+- Rust `load_spec` now reads gzipped seqspec YAML.
+- Python `seqspec check` and `seqspec onlist` can use auth profiles for remote resources.
+- Python local gzipped onlist validation now detects `.gz` files correctly.
+
 ## [0.4.0] - 2025-08-24
 
 ### Added
@@ -144,7 +170,7 @@ TODO:
 - `assay_spec` renamed `library_spec`
 - Reorganize specification document
 - Move contribution guidelines from `SPECIFICATION.md` to `CONTRIBUTION.md`
-- Move example `Region`s from `SPECIFCATION.md` to `seqspec/docs/regions`
+- Move example `Region`s from `SPECIFCATION.md` to `docs/examples/regions`
 - `seqspec index` defaults to indexing reads, `--region` indexes regions
 - Change descriptors of attributes `assay_id`, `doi`
 - `Assay` attribute `assay` changed to `assay_id`

docs/INSTALLATION.md

@@ -25,8 +25,21 @@ pip install seqspec
 uv pip install seqspec
 ```
 
-Verify the installation
+Install from source if you want the current working tree.
+
+```bash
+# Python package with the Rust core
+uv run maturin develop
+
+# standalone Rust CLI
+cargo install --path .
+```
+
+Verify the installation.
 
 ```bash
 seqspec --version
+seqspec auth path
 ```
+
+`seqspec` accepts plain YAML and gzipped YAML (`.yaml.gz`). Remote resources can be configured with `seqspec auth` and used with `--auth-profile` in commands such as `seqspec check` and `seqspec onlist`.