Subproject ngff-spec under specfications directory by jo-mueller · Pull Request #404 · ome/ngff

jo-mueller · 2026-01-07T15:24:58Z

Fixes #399

This is a proposed solution on how a joint layout of the ngff page and the future home of the spec, ome/ngff-spec could look like.

Key changes:

Deprecated bikeshed: The specs of .5 and 0.6.devX were converted into markdown/jupyter-book and are added as submodules under the specifications folder here in ngff
Moved submodules: As mentioned before, I removed the current submodule structure with the versions on the repo root and the spec versions living on different branches of this repo. Instead, the submodules point to different branches of the ngff-spec repo
Consistent build: Since the spec is now written in markdown, the respective md-pages can simply be added to a sphinx toctree directive over here on the ngff page - and as such be part of a uniform page layout. The URLs from which the spec documents were previously served (i.e. https://ngff.openmicroscopy.org/0.5/index.html now redirect to the respective location in the submodule:
/0.5/index.html --> /specifications/0.5/index.html
/0.5 --> /specifications/0.5
Schemas still served at same location: As right now, you can still access and download schemas from, say, https://ngff.openmicroscopy.org/0.5/schemas/image.schema

TODO

Include changelog, version history into specifications section?
Add the examples/schemas subsections for the older versions, too?
Fix providing html-rendered documents from json-schema-for-humans

- update build tools to handle ngff-spec contents - Make sure schemas are provided as html artefacts - deprecate bikeshed

github-actions · 2026-01-07T15:25:10Z

Automated Review URLs

lubianat · 2026-01-07T18:10:52Z

should we move with

change layout and add navbar #408
before this one?

preview on your link looks good, though

jo-mueller · 2026-01-08T08:56:43Z

@lubianat #408 makes total sense to go in first. On second and third thought, I think I may also undo the RTD deprecation in here. My original reason for doing this in the first place was the lack of customization options on how to integrate ngff-spec pages in the ngff page.

But since the placing of the spec submodules under the /specifications directory and the direct inclusion into the ngff page's toctree kind of solve that, maybe that's not an urgent need.

- specifications/0.5: Updated to f3729f5 (untrack built bs files) - specifications/0.6.dev2: Updated to da4606b (0.6.dev2 tag) - specifications/Dev: Updated to 05b8089 (main branch)

lubianat · 2026-01-19T15:02:49Z

I know this is WIP, but I don't really see 0.1, 0.2 etc there. Am I doing something wrong?

jo-mueller · 2026-01-19T15:21:40Z

@lubianat not at all :) We only merged the backport for 0.1...0.4 last week and I haven't updated the submodule configuration here yet. Will do asap!

jo-mueller · 2026-02-04T08:35:14Z

@lubianat thanks for the review

Adding latest as its own submodule is going to be tricky here because the entry in the table of contents is generated by the headings in the actual doc. So even adding 0.5 as a latest submodule doesn't make a difference because it carries the same header (i.e., 0.5) as the 0.5 submodule. I added a redirect to the confic though so that https://ngff--404.org.readthedocs.build/specifications/latest resolves correctly to https://ngff--404.org.readthedocs.build/specifications/0.5
header info rendering weirdly (now it does not render at all): I added the metadata that was just dumped into the document into the document's frontmatter section:
```
---
metadata is here now
---
```
apparently sphinx is able to parse the abstract field from that section, but not the rest 🙄. I can also remove the frontmatter section entirely from there 🤷‍♂️
copyright OME statement: What do you mean with that, exactly?
Dev uppercase: Needs to be fixed over at ngff-spec

lubianat · 2026-02-04T10:07:31Z

on the copyright statement:

on the current website, bikeshed docs have this:

maybe I am overthinking it, but it seems important

jo-mueller · 2026-02-04T11:21:57Z

I see! On the ngff-spec repo, the footer exists on the built pages:

Where do you think would be the correct place to put it? Would it collide with the copyright statement that's already on the page?

lubianat · 2026-02-04T11:28:28Z

Oh, I had not seen that. I think this may be more "political" than I can decide on, but perhaps the NGFF credit is enough?

Maybe that is a @joshmoore question, maybe for the PR review...

lubianat

I think it is in a safe shape to merge. Not perfect, perhaps, but good enough.

jo-mueller · 2026-02-05T11:52:03Z

I think this is ready to pull the trigger so we can go forward with other things :)

imagesc-bot · 2026-02-10T19:09:37Z

This pull request has been mentioned on Image.sc Forum. There might be relevant details there:

https://forum.image.sc/t/ngff-weekly-dev-update-thread/110810/56

joshmoore · 2026-02-16T04:31:05Z

Super excited to see this go in. 🎉 Thanks to @jo-mueller for driving the refactoring and to everyone for the review. There will likely be a series of smaller changes from here on out. Please feel free to open issues if you see anything that needs fixing.

Copilot

Pull request overview

This PR reorganizes the NGFF specifications by moving them from root-level submodules to a dedicated specifications directory, while transitioning from Bikeshed to Markdown/Jupyter-Book format. The changes enable unified documentation hosting at ngff.openmicroscopy.org with proper redirects from legacy URLs.

Changes:

Relocated version submodules (0.1-0.5, dev, latest) from repository root to specifications/ directory, pointing to the new ome/ngff-spec repository
Replaced Bikeshed-based build process with Jupyter-Book/MyST workflow for specification rendering
Added bibliography support and redirects to maintain backward compatibility with existing specification URLs

Reviewed changes

Copilot reviewed 21 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
specifications/index.md	Updated version links to use Markdown references and toctree structure instead of HTML
specifications/{dev,0.5,0.4,0.3,0.2,0.1}	New submodule references pointing to ome/ngff-spec branches
requirements.txt	Added sphinxcontrib-bibtex dependency, removed duplicate sphinx-reredirects
references.bib	Added bibliography entries for NGFF, Zarr, N5, and ome-zarr-py
latest, 0.5, 0.4, 0.3, 0.2, 0.1	Removed old root-level submodules
conf.py	Replaced Bikeshed processing with build_served_html() function for specifications
.readthedocs.yaml	Added Node.js 22 toolchain and pip installation for specifications/dev
.gitmodules	Updated all submodule paths to specifications/ directory with ome/ngff-spec URLs
.gitignore	Renamed _bikeshed directory to _html_extra
.github/workflows/validation.yml	Commented out validation workflow
.github/workflows/review.yml	Commented out review URL workflow
.github/workflows/dependabot.yml	Added Dependabot configuration for specifications/dev submodule
.codespellrc	Excluded references.bib from spell checking

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-16T15:55:46Z

specifications/index.md

-  <li> <a href="../0.2/index.html">0.2</a> March 2021</li>
-  <li> <a href="../0.1/index.html">0.1</a> November 2020</li>
-</ul>
+The current released version of the OME-Zarr specification is [0.5](0.5/ngff_spec/index.md).


The link path appears incorrect. Line 6 references 0.5/ngff_spec/index.md but line 13 in the toctree references 0.5/index.md. These paths should be consistent, and based on the toctree structure, line 6 should likely point to 0.5/index.md instead.

Suggested change

The current released version of the OME-Zarr specification is [0.5](0.5/ngff_spec/index.md).

The current released version of the OME-Zarr specification is [0.5](0.5/index.md).

@jo-mueller - I think copilot spotted a true bug here. The link there is leading to nothing indeed:

see https://ngff.openmicroscopy.org/specifications/index.html#0.5/ngff_spec/index.md

maybe we can add this to #440?

Copilot · 2026-02-16T15:55:46Z

conf.py

-            subprocess.check_call(
-                f"bikeshed spec {index_file} {output_file}", shell=True,
-            )
+        subprocess.check_call([sys.executable, script])


The subprocess call lacks error handling or informative error messages. If the pre_build.py script fails, users won't know which version or script caused the failure. Consider wrapping in a try-except block with a descriptive error message indicating the version and script path.

Suggested change

subprocess.check_call([sys.executable, script])

try:

subprocess.check_call([sys.executable, script])

except subprocess.CalledProcessError as e:

print(f'❌ Failed to run pre_build script for version {version} at {script}: return code {e.returncode}')

raise

except Exception as e:

print(f'❌ Unexpected error while running pre_build script for version {version} at {script}: {e}')

raise

This is the kind of thing I see as extra copilot noise. A decision with trade-offs that it is making. Could be better in theory, but in real life adds burdens around

Copilot · 2026-02-16T15:55:46Z

conf.py

-            shutil.rmtree(target_dir)
-        shutil.copytree(output_dir, target_dir)
+        # build jupyter-book docs in specification submodules
+        myst_file = glob.glob(f'specifications/{version}/**/myst.yml', recursive=True)[0]


Lines 123-124 define variables that are never used in the function. The myst_file variable is assigned but not referenced anywhere, and bikeshed_output is only used in the try-except block below. If myst_file serves no purpose, it should be removed to avoid confusion.

Suggested change

myst_file = glob.glob(f'specifications/{version}/**/myst.yml', recursive=True)[0]

ok clean up. not necessary, not harmful.

clean codewise — only the slightly painful cognitive burden of reviewing a bot suggestion (which is not nothing)

Subproject ngff-spec under specfications directory

a39f1fe

- update build tools to handle ngff-spec contents - Make sure schemas are provided as html artefacts - deprecate bikeshed

Update submodule configuration to use ome/ngff-spec

a3e8d50

jo-mueller mentioned this pull request Jan 8, 2026

merge contribution guide contents #410

Merged

jo-mueller added 12 commits January 8, 2026 14:07

rename development submodule to "Dev"

7926b1b

fix Dev submodule config

57a9fdb

fix links

6d84125

Create Dev

808c37a

bring back RTD

944496a

add node to RTD tools

d826d12

Update submodules to latest commits

87fb6b0

- specifications/0.5: Updated to f3729f5 (untrack built bs files) - specifications/0.6.dev2: Updated to da4606b (0.6.dev2 tag) - specifications/Dev: Updated to 05b8089 (main branch)

invoke build scripts in submodules

76fa183

fix index location

27d77c6

update commit

d26cbbf

do not build jupyter book here

365094e

add 0.4

9eee808

lubianat mentioned this pull request Jan 12, 2026

ngff repo structural changes #399

Closed

jo-mueller added 9 commits January 12, 2026 12:27

build books

8228f2b

update modules

8e2462f

add 0.1 and 0.2

87871c3

use bibtex references and parsing on page

b8f036f

update submodules

8767c3a

update submodules

f088baf

Merge remote-tracking branch 'upstream/main' into subproject-ngff-spec

fb9fe03

skip references.bib in codespell

9efec31

use ngff-spec as origin for submodules

05b5e37

jo-mueller added 4 commits February 4, 2026 00:14

updated submodules

12d06f8

update toctree

9505491

install deps from correct location

98bd5b4

add redirect from latest to 0.5

93ce667

updated redirects so that old bs files are still discoverable

efe5d7c

lubianat mentioned this pull request Feb 4, 2026

NGFF PR Review (2026-02-05) German-BioImaging/incubator#38

Closed

jo-mueller added 4 commits February 5, 2026 10:50

remove latest submodule

5ca3bbc

remove latest from section navigation

635bc96

Update submodule URLs and branches

805310f

update submodules

1c8a816

lubianat approved these changes Feb 5, 2026

View reviewed changes

jo-mueller requested review from clbarnes and joshmoore February 5, 2026 11:51

jo-mueller changed the title ~~WIP: Subproject ngff-spec under specfications directory~~ Subproject ngff-spec under specfications directory Feb 10, 2026

clbarnes approved these changes Feb 11, 2026

View reviewed changes

jo-mueller added 2 commits February 12, 2026 10:21

bump commit

35da679

feat: add dependabot for spec dev head

dece0ae

joshmoore merged commit b56fd00 into ome:main Feb 16, 2026
3 checks passed

This was referenced Feb 16, 2026

No easy way to switch between versions of the specification on website #345

Closed

reactivate review action #440

Merged

lubianat requested a review from Copilot February 16, 2026 15:54

Copilot AI reviewed Feb 16, 2026

View reviewed changes

jo-mueller mentioned this pull request Feb 25, 2026

v0.6dev3 spec page is missing "scene" #447

Closed

	The current released version of the OME-Zarr specification is [0.5](0.5/ngff_spec/index.md).
	The current released version of the OME-Zarr specification is [0.5](0.5/index.md).

-        subprocess.check_call([sys.executable, script])
+        try:
+            subprocess.check_call([sys.executable, script])
+        except subprocess.CalledProcessError as e:
+            print(f'❌ Failed to run pre_build script for version {version} at {script}: return code {e.returncode}')
+            raise
+        except Exception as e:
+            print(f'❌ Unexpected error while running pre_build script for version {version} at {script}: {e}')
+            raise

Conversation

jo-mueller commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TODO

Uh oh!

github-actions bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Automated Review URLs

Uh oh!

lubianat commented Jan 7, 2026

Uh oh!

jo-mueller commented Jan 8, 2026

Uh oh!

lubianat commented Jan 19, 2026

Uh oh!

jo-mueller commented Jan 19, 2026

Uh oh!

jo-mueller commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lubianat commented Feb 4, 2026

Uh oh!

jo-mueller commented Feb 4, 2026

Uh oh!

lubianat commented Feb 4, 2026

Uh oh!

lubianat left a comment

Choose a reason for hiding this comment

Uh oh!

jo-mueller commented Feb 5, 2026

Uh oh!

imagesc-bot commented Feb 10, 2026

Uh oh!

joshmoore commented Feb 16, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

lubianat Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

lubianat Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

lubianat Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

jo-mueller commented Jan 7, 2026 •

edited

Loading

github-actions bot commented Jan 7, 2026 •

edited

Loading

jo-mueller commented Feb 4, 2026 •

edited

Loading