Configure joint webpage layout for spec/examples/schemas

[jo-mueller]

Well. This is my take on tying together the contents of the spec (specification text, examples, schemas) together in a single view. The contents on this branch are built on this page.

Major changes

• Deprecated bikeshed: I found a key necessity would be to really embed the specification text on the page and not just link out to it. This is, to my knowledge, not possible with bikeshed. The later just produced html pages which can be linked to, but nit embedded, which makes navigation harder.
• Moved over to MyST-powered markdown: MyST provides a lot of powerful formatting for all sorts of content and easily reproduces some of the built-in amenities of bikeshed plus all the other features of markdown which I think will add greatly to the readability and accessibility of the spec document
• Autogenerated human-readable schemas and examples Used standard json parsing and jsonschemaforhumans to generate markdown versions of both that can just be linked into the documents. MyST cross-references are automatically created on the fly, which could be used to have a better referencing between spec text and examples/schemas, if desired.
• ** Built by Jupyter-book**: Doc pages build now uses jupyter-book, which is built on top of sphinx, but I find the configuration and content organization a bit easier than standalone sphinx. I added instructions on how to locally build everything
• Split content: I moved some of the contents of the spec text (version history, citing, etc) into separate sections.

Open issues

• Broken references: Looking at the markdown files of the schemas, they look nice at first glance, but some of the references between definitions don't seem to work (a lot of warnings during build, too). Not sure why this is the case - I opened an issue at jsonschema-for-humans but it could as well be an error in how I am building the document.
• Repository structure: Is the way I arranged documents clear?
• Authors I'll add a citations.cff file before the first real release of this so that acknowledgement is expanded to all contributors (see this PR)

Looking forward to your feedback

Long Copilot description

This pull request introduces a comprehensive overhaul of the documentation build system and supporting files for the NGFF specification. The changes migrate the documentation to a Jupyter Book and MyST-based workflow, automate the generation of example and schema documentation, and update example metadata to the latest specification version. The PR also modernizes configuration, citation, and contribution guidance.

Documentation build system migration and automation:

• Added a new .readthedocs.yaml configuration to enable building the documentation with Read the Docs using Python 3.13 and custom pre-build steps for Jupyter Book and schema/example generation (.readthedocs.yaml).
• Introduced docs/pre_build.py, a script that automatically generates Markdown documentation from JSON examples and schemas, including cross-references and summary tables (docs/pre_build.py).
• Updated docs/requirements.txt to include all dependencies needed for the new Jupyter Book and schema documentation workflow (docs/requirements.txt).

Jupyter Book configuration and structure:

• Added a comprehensive _config.yml for Jupyter Book, specifying book metadata, repository links, HTML footer, MyST and Sphinx extensions, and output settings (_config.yml).
• Defined a new table of contents in _toc.yml to organize the book structure, including chapters for examples, schemas, and contributor/citation/version pages (_toc.yml).

Content updates and modernization:

• Added or updated documentation content: a new citation page with bibliography integration (citing.md), a contribution guide with formatting and referencing instructions (contribute.md), and a placeholder for JSON examples (docs/examples.md). [1] [2] [3]
• Added a BibTeX file with references for citation and bibliography support (references.bib).

Specification example updates:

• Updated the examples/multiscales_strict/multiscales_example.json to use version "0.6dev2" and the new coordinate system structure, aligning with the latest NGFF specification.

Cleanup and removal of legacy files:

• Removed legacy HTML include files (header.include, copyright.include)
  as these are now handled by Jupyter Book configuration and templates. [1] [2]

These changes collectively modernize the documentation workflow, improve maintainability, and ensure that examples and schemas are always up-to-date and easy to navigate.

[clbarnes]

Worth noting that json-schema-for-humans is a couple of drafts out of date. The differences in JSON Schema are probably not major, for our purposes, but it makes me think twice about it - draft 7 was made obsolete in 2019.

I'd also be concerned about duplicating information/ having two sources of truth when it comes to the prose vs the description fields in the JSON Schema - already the case to an extent, of course.

Another question - is this layout still amenable to the existing model of ome/ngff representing the "landing page" and then the contents of this repo being just the spec? I think originally there were no build-related files in here, but there are in this change.

[dstansby]

At a glace looks really nice ✨ ! One quick immediate thought: Jupyter book 1.x is no longer undergoing active development, so you may be better switching to Jupyter book 2.x straight away, even if it is in beta. I did this at https://heftie-textbook.readthedocs.io/en/latest/ and it's working well

[jo-mueller]

Hey there, thanks for looking into it. I wasn't aware of the updates in json in the last few years, there's also been some discussion over at jsonschema-for-humans on the matter.

For now, I'm jus ttrying to recreate the currently existing content of the ngff ewbpage - although the schema pages are veeeeery well hidden there.

Would also be glad for a pointer to a more state-of-the-art tool to spawn readable schema artifacts as markdown files. I'm looking into jsonschema_markdown and sphinx-jsonschema atm.

Edit: Just checked, a very widely used tool (jsonschema2md) apparently also only support json schema standards up until the 2019 revision. With that as a reference I think that'd be good enough for me. I would have liked the jsonschema sphinx directive as well. The vocabulary there is even older, so meh, but may be worth exploring whether it may do the trick for us, still.

[jo-mueller]

@dstansby I just upgraded to Jupyter-book and it looks super-neat! I can't seem to get the readthedocs.yml just right, though...care to give it a look?

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.13"
    nodejs: "22"
  jobs:
    post_install:
      - pip install -r docs/requirements.txt
    pre_build:
      # Generate the Sphinx configuration for this Jupyter Book so it builds.
      - "python ./docs/pre_build.py"

    build:
      html:
        - jupyter book build --html --execute --strict --ci
        - mkdir -p $READTHEDOCS_OUTPUT/html
        - cp -r _build/html/* $READTHEDOCS_OUTPUT/html/

Edit: Ok, I think I'll just go ahead and merge this for the time being - upgrading to Jupyter book 2 can come in a separate PR.

[will-moore]

Looks great GFI! 🚀

[clbarnes]

2019 is only one draft behind (even though it's only a year more recent than json-schema-for-humans). This is what happens when specifications don't reach 1.0, I guess 😬