Repository navigation
Release: dev into main - #167
Open
davehorsfall wants to merge 13 commits into
Open
davehorsfall wants to merge 13 commits into
davehorsfall wants to merge 13 commits into
Conversation
The docs site has been stale since 16 September. `deploy-docs.yml` has run twice in its life, and the one push since then that matched its path filter produced no workflow runs at all, so nothing rebuilt and nothing could tell. A push-triggered, path-filtered deploy has no way to notice it was missed. So it now deploys on `release: published`, checking out the tag. Published API documentation should describe the published package, and this removes the "did that push match the filter?" question entirely. Same reasoning as the app's own deploy. A manual trigger covers refreshing the site without cutting a release. The guard before the rsync checked that one file was non-empty, in front of a `--delete-unmatched-destination-objects` that removes whatever the build does not contain. A build that emitted an index page and lost the rest would have passed it and emptied the bucket. It now checks file count and total size against the 73 files and 2.4MB a real build produces. Nothing built the docs before main, so a break arrived there first. A pull request into any branch now builds them, which is nineteen seconds. anndata-zarr had no API documentation at all -- it is a published package with no reference pages. It is now an entry point like the other two. Warnings are errors now, and making that pass meant exporting types that exported API already referenced: Events, MultichannelConfig and SingleChannelConfig from the viewer, and ObservationControlsProps, ColourProps and ObservationMetadata from anndata-zarr. Each was reachable from something public and documented as a dead link. This widens the published type surface, additively. The quick start documented a different package. It said to install @hms-dbmi/vizarr and import a default export this package does not have, and its example used a viewState it never defined -- every line of it was wrong. Rewritten against the real exports, with createViewer, labels and the theme escape hatch alongside. The styling is layered over typedoc-github-theme as custom property overrides rather than replacing it; that theme is a sound base and the only thing wrong with it was that the site looked like GitHub. Accents come from the three channels of the vizarr mark. Both colour schemes still work: the viewer is dark because it wraps images in as little light as possible, but documentation is long-form reading and the reader's preference should win. The brand blue measures 2.65:1 on white, so light mode uses a darkened version of the same hue at 5.72:1 and dark mode keeps the original at 6.89:1. `build:docs` ran bare typedoc, and typedoc has to resolve `@biongff/vizarr` because roi-selector and anndata-zarr import it for types. Those types only exist once the viewer is built, so on a clean checkout there is no viewer/dist and the run fails -- which it did, the first time this workflow had fired since 16 September. It had been broken since 22 September, when the logging refactor added that import; nothing noticed because the deploy had not run in between. The stale site was hiding a broken build. The script now builds the viewer first. Lastly `pnpm docs:dev`, which serves the site and rebuilds as you edit. A full typedoc pass is about twenty seconds, far too slow to iterate on a stylesheet, so a CSS change is copied straight into the output instead -- measured at 255ms to live. The reload listener is injected as the page is served, so the build output stays what gets published. Closes #146 Co-Authored-By: Claude Opus 5 <[email protected]>
Merging dev brought in the workflow overhaul from #152, so the two docs workflows now have a composite setup action to use and a naming convention to follow. docs.yml becomes build-docs.yml / "Build docs", pairing with deploy-docs.yml / "Deploy docs", and takes the composite action instead of its own copy of the setup block. Its path filter grows an entry for .github/actions/setup, because the build now depends on it and a change there should not first show up at release. It also gains concurrency, and narrows to pull requests into main and dev -- it said "any branch" when test.yml only covered main, and it would be odd for a pull request into a feature branch to have its docs checked but not its types. deploy-docs.yml gains a comment above the Google authentication step rather than a change. Moving it to the release trigger means it now runs at a tag ref, and this workflow has only ever run from branches. That is the same change that broke the Pages deploy, where the environment allowed main and dev and no tags, and every release deploy was refused after a clean build. The equivalent gate here lives in Google: the workload identity provider's attribute condition and the principalSet on the service account. If either keys on the ref rather than the repository, this will fail at the next release, and there is no way to test it short of one. CLAUDE.md gains docs:dev and build:docs in the commands table. Refs #146 Co-Authored-By: Claude Opus 5 <[email protected]>
The example used idr/zarr/v0.5/idr0062A/6001240.zarr, which 404s. The same image is served under v0.4, which responds. Checked by fetching .zattrs rather than the store root, since a bare zarr URL is a prefix and 404s even when the store is there -- which is also why this was not obvious. Co-Authored-By: Claude Opus 5 <[email protected]>
Publish the API docs on release, check them on pull requests, and make the site look like vizarr
✅ Deploy Preview for biongff-vizarr ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
🟡 Changes recommended
Documentation previews fail on fresh checkouts, manual deployments can publish unreleased content instead of main, and malformed URLs can crash the development server.
3 open issues
What changed in this PR
This release PR updates Vizarr’s API documentation, aligns publication with releases, and adds a local documentation preview workflow.
Changes:
- Publish docs from release tags and validate documentation builds on pull requests using shared setup.
- Add Vizarr styling, expand the quick start, and include the AnnData plugin in the API reference.
- Export referenced public types and add a live-reloading documentation server.
| File | Description |
|---|---|
viewer/src/index.tsx |
Re-exports event and image configuration types. |
viewer/src/api.tsx |
Exports the viewer event type. |
typedoc.json |
Adds AnnData docs, branding, and strict warning handling. |
scripts/docs-dev.mjs |
Adds local serving, rebuilds, and live reload. |
package.json |
Builds the viewer before docs and adds docs:dev. |
docs/viewer/theme.css |
Adds light and dark documentation styling. |
docs/viewer/introduction.md |
Expands setup examples and corrects the example image URL. |
CLAUDE.md |
Documents preview and documentation build commands. |
anndata-zarr/typedoc.json |
Configures the plugin’s documentation entry point. |
anndata-zarr/src/index.ts |
Re-exports types used in the public API. |
anndata-zarr/src/components/ObsSelect.tsx |
Exports observation control props. |
.github/workflows/deploy-docs.yml |
Deploys release documentation with build-size checks. |
.github/workflows/build-docs.yml |
Adds pull-request documentation builds. |
Review effort: Balanced
Comment on lines
+33
to
+35
| # An empty ref is the default branch, which is what an unqualified manual | ||
| # run should get. | ||
| ref: ${{ github.event.release.tag_name || inputs.tag }} |
| building = true; | ||
| const started = Date.now(); | ||
| process.stdout.write("building... "); | ||
| const child = spawn("npx", ["typedoc"], { cwd: root, stdio: ["ignore", "pipe", "pipe"] }); |
|
|
||
| http | ||
| .createServer((req, res) => { | ||
| const url = decodeURIComponent((req.url ?? "/").split("?")[0]); |
The bar was a fixed 5% of the viewport labelled with whatever that happened to measure, to five significant figures. On an IDR image it read "8.6721micrometer" -- correct, and useless, because a scale bar exists so a round length can be laid against the image by eye. That followed from the unit. NGFF spells units as UDUNITS-2 names and viv's `sizeToMeters` reads SI symbols, so `micrometer` could not be measured and `snap` had to stay off. Mapping the names onto symbols is what makes snapping possible; `snap: true` on its own throws `Received unknown unit` from inside `renderLayers`, which our own fixtures would trigger. Two things are now refused rather than drawn. A unit viv cannot express as metres -- `foot`, `inch`, `mile`, `yard`, `parsec`, and `angstrom`, which is 10^-10 and has no SI prefix. And a unit that is absent, because `sizeToMeters` returns the size unchanged for an empty unit, which is to say it reads it as metres: the Xenium images that declare no unit would carry an authoritative-looking bar out by six orders of magnitude. Nothing here asks viv to reject what it cannot measure. Its prefix test is `unit.substring(0, unit.length - 1)` and never checks that what remains is `m`, so `ft` parses as femto and renders `25fm`. Measured, and kept as a test. Measured on idr0062A/6001240_labels.zarr at the same view: "8.6721micrometer" before, "10µm" after. Refs #176. The mapping and `snap: true` are ported from BioNGFF/biongff-viewer#46; the guard is what keeps them from throwing. Co-Authored-By: Claude Opus 5 <[email protected]>
The Observations panel came up empty whenever any single column could not be read, showing two headings with nothing under either. Columns that had been read perfectly well were discarded along with the one that had not. `Promise.all` is fail-fast: one rejection rejects the batch, and the outer catch turned that into `[]`. Settling each column on its own keeps the rest, and each rejection is now logged with the column's name -- a column absent from both the panel and the log is indistinguishable from one the table never had. The dividers are drawn only when something falls under them. That was cosmetic before and is not now: partial lists become the ordinary case rather than the exception. Measured against the new fixtures, before and after: table-zarr2 ["region", "area", "passed"] -> unchanged table-zarr3 [] -> ["area", "passed"] Adds the first offline tests this package has had; everything in `anndata-zarr/tests/` needed a server we do not run, so none of it ran on a pull request. The two failing columns in the zarr v3 fixture fail for reasons no zarrita version papers over -- a node that is not there, and a dtype in nobody's table. That is deliberate: this package declares zarrita 0.5.0 and the viewer declares 0.6.2, and the application bundles one copy for both, so a fixture turning on a dtype only one of them supports would assert something no user could meet. The tables are named for the zarr format rather than a version number, because unlike the images beside them they answer to no OME-NGFF version at all. Refs #178. Ported from BioNGFF/biongff-viewer#44, which catches per column and guards the same dividers. Co-Authored-By: Claude Opus 5 <[email protected]>
A rejected promise is a perfectly good cache entry as far as QuickLRU is concerned, so a read that failed was returned for the rest of the session and the store never asked again. Measured against a server made to refuse and then relent, which is what re-authenticating or a restarted backend looks like from the client: 1st: Unexpected response status 403 Forbidden 2nd after re-auth: still fails -- "403 Forbidden" requests the server saw on the 2nd attempt: 0 The server was willing. Nothing asked it. `getRange` already dropped its entry on failure; `get` did not. This gives `get` the same `.catch`, which is the whole change. Everything that is not "absent" lands there -- a 401, a 403, a 502, a dropped connection -- so a blip during a load used to cost that chunk until the page was reloaded. An absent key still caches. A 404 is how zarrita discovers a node is not there, a group with no labels or a well with no image, and asking twice would cost a request for every one of them. The tests count what the server receives, because that is the only way to tell a cached answer from a fresh one. Reverting the fix fails exactly one of them. Closes #182. Unblocks #181: no sign-in-and-retry design can work while the retry never reaches the network. Co-Authored-By: Claude Opus 5 <[email protected]>
fix(viewer): stop caching a read that failed
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
fix(anndata): let one unreadable obs column cost only itself
fix(viewer): measure the scale bar in a unit viv can read
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Merging this publishes a release.
devis 13 commit(s) ahead ofmain.Fixes
Every commit