PR rendering CI

[ivirshup]

The links for rendered versions of the PRs haven't been working for me for at least the last week. Does anyone know what's up with this?

I'm also wondering if this whole process could be improved by building the html and deploying it somewhere ( like readthedocs PR builds). Even when the links were working they did take a while to load. It would also be nice to see build errors and warnings from CI.

[joshmoore]

The W3 service that generates the bikeshed-based pages has definitely become unreliable.

Additionally, I've searched for solutions for PR previews of GitHub Pages but to no avail. The closest "recommendation" I've seen to date is to create a repository per PR.

So 👍 from me.

[ivirshup]

PR previews of GitHub Pages

Yeah, this doesn't seem straight forward. Maybe we could just use readthedocs?

I think we can also do some partial fixes easily (like, at least checking that the doc builds) even if we can't view it super easily.

---

Some workarounds for viewing the rendered spec

• Rendering by pasting the index.bs url here: https://api.csswg.org/bikeshed/ works
• pipx install bikeshed, bike shed update, and bikeshed spec from the version root directory (e.g. latest, 0.4) will generate a rendered version
  • bikeshed pins its dependencies to specific versions, so don't install it into an environment with anything else

More info on running bike shed (including some CI actions) here: https://tabatkins.github.io/bikeshed/

[ivirshup]

@joshmoore, I'm not sure it's the w3c service that's preventing rendering at the moment. I think it's the github action.

The links in the tables PR comment looks like:

http://api.csswg.org/bikeshed/?url=https://raw.githubusercontent.com/ome/ngff//latest/index.bs

When it should look like:

http://api.csswg.org/bikeshed/?url=https://github.com/ome/ngff/raw/cc83a82c716670fb60d2d7f8a89f4f700a17b788/latest/index.bs

The action doesn't seem to be using the environment variable properly. You can also see this in the action logs.

[ivirshup]

@joshmoore, I suspect rtd may be a bit of a pain here because we would have to work around sphinx.

But a colleague has recently used netlify to host their PR builds (see scverse/scverse.github.io#63), which I found fairly straight forward to set up. See an example here: ivirshup#1

[jburel]

If we start to expand this repository to include more than just the spec e.g. list of samples data (#140), list of tools as discussed during OME 2022. RTD could be a valid option
Happy to look into the conversion

[joshmoore]

As a side note, discussing with @jstriebel, there was the feeling that perhaps another spec mechanism for https://github.com/zarr-developers/zarr-specs would be beneficial. Perhaps we can double up the work in identifying one.

[joshmoore]

With the move to readthedocs for PRs, this is now implemented.