Upgrade to jupyter book 2

[jo-mueller]

Supersedes #16

Upgrade to Jupyter book 2

Title. Re-organized some of the metadata fields into the new and upcoming Jupyter book 2 layout.

Open question: The introduced myst.yml file provides nice formatting for author information. Maybe that could be a good place to gather all the contributors to the spec and subsequently autogenerate a citation.cff file?

Link to built docs

Long co-pilot description

This pull request modernizes and restructures the NGFF specification repository to improve documentation building, organization, and clarity. The most significant changes include migrating from Jupyter Book to MyST for documentation, updating build scripts and configuration files, and refining cross-referencing and navigation throughout the docs. These updates streamline the build process, enhance maintainability, and improve the user experience for contributors and readers.

Documentation Build System Migration and Improvements:

• Migrated documentation build from Jupyter Book to MyST, introducing a new ngff_spec/myst.yml configuration for project metadata, table of contents, export options, and theme pinning. The legacy _config.yml and _toc.yml files were removed. (ngff_spec/myst.yml, _config.yml, _toc.yml) [1] [2] [3]
• Updated .readthedocs.yaml to use Python 3.12, Node.js 22, and the uv package manager for dependency management, reflecting the new build process and directory structure. (.readthedocs.yaml)

Directory and Script Refactoring:

• Refactored the build script (pre_build.py → ngff_spec/pre_build.py) to generate documentation files in new locations (examples, schemas, _generated) and to create a dynamic footer for the site. Markdown and cross-referencing logic were improved for both examples and schemas. (ngff_spec/pre_build.py) [1] [2] [3]
• Updated references and file paths in documentation and scripts to match the new directory structure, ensuring consistency and correct linking. (ngff_spec/examples.md, ngff_spec/schemas.md) [1] [2]

Cross-referencing and Navigation Enhancements:

• Standardized cross-reference syntax in markdown files for both examples and schemas, using (#reference-name) for internal links and updating all related documentation accordingly. (ngff_spec/contribute.md, ngff_spec/examples.md, ngff_spec/schemas.md, ngff_spec/pre_build.py) [1] [2] [3] [4]
• Improved navigation for metadata examples and schemas by generating index files with organized links and sections for each example and schema type. (ngff_spec/examples.md, ngff_spec/schemas.md, ngff_spec/pre_build.py) [1] [2] [3]

Content and Formatting Updates:

• Updated documentation content to use YAML front matter for metadata, improved section structure, clarified instructions for contributors, and standardized code and reference blocks. (ngff_spec/specification.md, ngff_spec/contribute.md) [1] [2] [3] [4] [5] [6] [7] [8] [9]
• Added a new README.md describing the repository, its contents, and providing a link to the built documentation. (README.md)

[github-actions]

Automated Review URLs

• Readthedocs

[Copilot]

Pull Request Overview

This PR upgrades the documentation build system from Jupyter Book v1 to v2, migrating configuration to the MyST format. The changes reorganize project metadata, update file paths to a new directory structure, and modernize the build process with updated dependencies and tooling.

Key changes:

• Migration from legacy _config.yml and _toc.yml to new myst.yml configuration format
• Updated build scripts to generate content in restructured directories (_generated/ instead of ngff_spec/generated/)
• Standardized cross-reference syntax throughout documentation using (#reference) format

Reviewed Changes

Copilot reviewed 11 out of 13 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
pyproject.toml	Introduces project configuration with Jupyter Book 2.0.0b3 and MyST dependencies
ngff_spec/myst.yml	New MyST configuration defining project metadata, table of contents, and theme settings
_config.yml	Removed legacy Jupyter Book v1 configuration
_toc.yml	Removed legacy table of contents configuration
.readthedocs.yaml	Updated build configuration to use Python 3.12, Node.js 22, and uv package manager
ngff_spec/specification.md	Updated with YAML frontmatter and standardized cross-references
ngff_spec/pre_build.py	Refactored to generate content in new directory structure and create dynamic footer
ngff_spec/examples.md	Regenerated index with new structure and cross-reference links
ngff_spec/schemas.md	Updated paths and cross-references for new directory structure
ngff_spec/contribute.md	Updated build instructions and cross-reference syntax examples
README.md	New repository description with links to documentation

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}