Upgrade to jupyter book 2 (#20)

* upgrade to Jupyter book 2

* correctly mark examples

* bump mystmd dependency

* pin mystmd

* hashpin template

* remove legacy dependencies

* Create README.md for OME-NGFF specification

* remove legacy files

* use auto-built footer for copyright

* Fix cross-reference

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Fix empty cross-reference

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Typo

* Update README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: jo-mueller

.readthedocs.yaml

@@ -1,19 +1,20 @@
 version: 2
-
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.13"
+    python: "3.12"
+    nodejs: "22"
   jobs:
+    post_install:
+      - pip install uv
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --link-mode=copy
+      
     pre_build:
-      # Generate the Sphinx configuration for this Jupyter Book so it builds.
-      - "jupyter-book config sphinx ."
-      - "python ./docs/pre_build.py"
-
-python:
-  install:
-    - requirements: docs/requirements.txt
-
+      # Run the script that autogenerates content before building the docs
+      - "uv run python ngff_spec/pre_build.py"
 
-sphinx:
-  configuration: conf.py
+    build:
+      html: 
+        - cd ngff_spec/ && jupyter book build --html --ci
+        - mkdir -p $READTHEDOCS_OUTPUT
+        - mv ./ngff_spec/_build/html $READTHEDOCS_OUTPUT

README.md

@@ -0,0 +1,10 @@
+# OME-NGFF file format specification
+
+NGFF is an initiative by the bioimaging community to develop imaging format specifications to
+address issues of scalability and interoperability.
+
+This repository contains the central [specification text](./ngff_spec/specification.md),
+a comprehensive list of [metadata examples](./ngff_spec/examples)
+as well as [json schemas](./ngff_spec/schemas) to validate written ome-zarr image data. 
+
+The built documentation including contribution hints can be found **[here](https://ngff-spec.readthedocs.io/en/latest/specification.html)**.

_config.yml

@@ -13,7 +13,7 @@ Build and inspect changes to the documentation before submitting a PR.
 To do so, you first need to install the necessary dependencies:
 
 ```bash
-pip install -r requirements.txt
+pip install .
 ```
 
 This document uses [jupyter-book](https://jupyterbook.org) to generate the pages
@@ -22,8 +22,8 @@ After installing these via the dependencies,
 navigate into the repository on your machine and build the book using the following command:
 
 ```bash
-python pre_build.py
-jupyter-book build .
+python ngff_spec/pre_build.py
+jupyter book build ngff_spec
 ```
 
 You'll find the built webpages under `_build/html`.
@@ -48,7 +48,7 @@ It is recommended to use the following syntax in this document for consistency:
 
 ```
 anchor: (your-reference-name)=
-reference: [This is a reference](your-reference-name)
+reference: [This is a reference](#your-reference-name)
 ```
 
 #### Admonitions
@@ -85,6 +85,8 @@ use this syntax:
 Some informative text about your example
 ```{literalinclude} path/to/example.json
 :language: json
+:linenos:
+:tab-width: 2
 ```
 ````
 `````

_toc.yml

@@ -1,3 +1,59 @@
-# JSON Examples
+---
+title: NGFF metadata JSON Examples
+short_title: JSON Examples
+---
 
-This document contains JSON examples for ngff-compliant metadata layouts.
+This section contains JSON examples for various metadata layouts.
+
+## bf2raw
+- [image](#examples:bf2raw:image)
+- [plate](#examples:bf2raw:plate)
+
+## coordSystems
+- [arrayCoordSys](#examples:coordSystems:arrayCoordSys)
+
+## label_strict
+- [colors_properties](#examples:label_strict:colors_properties)
+
+## multiscales_strict
+- [multiscales_example](#examples:multiscales_strict:multiscales_example)
+- [multiscales_example_relative](#examples:multiscales_strict:multiscales_example_relative)
+- [multiscales_transformations](#examples:multiscales_strict:multiscales_transformations)
+
+## ome
+- [series-2](#examples:ome:series-2)
+
+## plate_strict
+- [plate_2wells](#examples:plate_strict:plate_2wells)
+- [plate_6wells](#examples:plate_strict:plate_6wells)
+
+## subspace
+- [subspaceMultidim](#examples:subspace:subspaceMultidim)
+- [subspacePermute](#examples:subspace:subspacePermute)
+
+## transformations
+- [affine2d2d](#examples:transformations:affine2d2d)
+- [affine2d3d](#examples:transformations:affine2d3d)
+- [bijection](#examples:transformations:bijection)
+- [bijection_verbose](#examples:transformations:bijection_verbose)
+- [byDimension1](#examples:transformations:byDimension1)
+- [byDimension2](#examples:transformations:byDimension2)
+- [byDimensionInvalid1](#examples:transformations:byDimensionInvalid1)
+- [byDimensionInvalid2](#examples:transformations:byDimensionInvalid2)
+- [byDimensionXarray](#examples:transformations:byDimensionXarray)
+- [coordinates1d](#examples:transformations:coordinates1d)
+- [displacement1d](#examples:transformations:displacement1d)
+- [identity](#examples:transformations:identity)
+- [inverseOf](#examples:transformations:inverseOf)
+- [mapAxis1](#examples:transformations:mapAxis1)
+- [mapAxis2](#examples:transformations:mapAxis2)
+- [rotation](#examples:transformations:rotation)
+- [scale](#examples:transformations:scale)
+- [sequence](#examples:transformations:sequence)
+- [sequenceSubspace1](#examples:transformations:sequenceSubspace1)
+- [translation](#examples:transformations:translation)
+- [xarrayLike](#examples:transformations:xarrayLike)
+
+## well_strict
+- [well_2fields](#examples:well_strict:well_2fields)
+- [well_4fields](#examples:well_strict:well_4fields)

ngff_spec/contribute.md

@@ -0,0 +1,34 @@
+version: 1
+project:
+  title: Next-generation file format specification
+  authors:
+    - name: NGFF-community
+  github: ome/ngff-spec
+  bibliography:
+    - references.bib
+  exports:
+    - format: pdf
+      template: plain_latex_book
+      output: exports/book.pdf
+  toc:
+    - file: specification.md
+    - file: examples.md
+      children:
+        - pattern: _generated/examples/*
+    - file: schemas.md
+      children:
+        - pattern: _generated/schemas/markdown/*
+    - file: contribute.md
+    - file: citing.md
+    - file: version_history.md
+site:
+  options:
+    logo: https://www.openmicroscopy.org/img/logos/ome-logomark.svg
+    folders: true
+    hide_myst_branding: true
+  parts:
+    footer: footer.md
+
+  # Temporarily hash-pin the theme.
+  # See: https://github.com/jupytercon/jupytercon2025-developingextensions/issues/6
+  template: "https://github.com/myst-templates/book-theme/archive/de4c1e9c09c6cd12fc529c1f22e8abf8e7f35381.zip"