From 7c19b5928e90c2a7627b4ab12e501884319bd607 Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Mon, 16 Feb 2026 11:15:58 +0100 Subject: [PATCH 1/3] More help for contributing --- contributing/index.md | 51 +-------- contributing/specification/index.md | 164 ++++++++++++++++++++++++++++ contributing/website/index.md | 42 +++++++ 3 files changed, 212 insertions(+), 45 deletions(-) create mode 100644 contributing/specification/index.md create mode 100644 contributing/website/index.md diff --git a/contributing/index.md b/contributing/index.md index 1f36dea6..5badddb7 100644 --- a/contributing/index.md +++ b/contributing/index.md @@ -3,52 +3,13 @@ Thanks for taking the time to contribute to the `OME-Zarr` specification! We welcome contributions from anyone. -The below sections explain how to contributed in different ways to the -`OME-Zarr` specification. +Below you find links and guidelines on how to contribute to specific parts of the NGFF project. -## Changes to the specification - -Any suggested major changes to the `OME-Zarr` specification should be opened as -request for comment (RFC) documents. - -In the future we will flesh out this page with a guide to RFCs, but in the -meantime the RFC process is outlined in the -[Implementation section of RFC 1](../rfc/1/index.md#implementation). - -### Comment on a Request For Comment (RFC) - -If you want to leave a suggestion or comment on an RFC that is under review, -please leave a comment in a new page under the "comments/" directory for the -relevant RFC. A template is also available for formatting your comment: -[template](../rfc/1/templates/review_template). - -### How to change the specification - -To make a change such as the end-product of an RFC or a minor correction to the currently developed specification version, -please do so via a pull request (PR) against the `main` branch of the [ome/ngff-spec](https://github.com/ome/ngff-spec) repository. -This repository contains the specification documents in Markdown format, -json examples and the schema files for validation. - -## Changes to this website - -The repository for this website is [ome/ngff](https://github.com/ome/ngff). -Contributions to these pages are welcome as issues or PRs. - -To do so, create a fork of the ``ome/ngff`` repository, make your changes, -and submit a pull request (PR) against the `main` branch. - -### Syntax -This repository uses Sphinx to publish a ReadTheDocs site at https://ngff.openmicroscopy.org in the [Sphinx Book Theme](https://sphinx-book-theme.readthedocs.io/en/stable/). - -[MyST](https://myst-parser.readthedocs.io/en/latest/) syntax can be used in addition to basic Markdown and HTML. - -### Configuration -Edit [conf.py](./conf.py) with options from the [Sphinx Book Theme](https://sphinx-book-theme.readthedocs.io/en/stable/). The [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide) user guide may also have more up to date instructions for configuration properties. - -### Previews -Each PR receives a unique preview URL of the format `https://ngff--.org.readthedocs.build/` where `` is the PR number. This link is also posted to each PR by the Github actions bot in an "Automated Review URLs" comment as the "Readthedocs" link. - -Please check that your changes render correctly at this URL. New commits will automatically be live at the PR url after a few minutes. +```{toctree} +:maxdepth: 1 +:glob: +*/index +``` ## Contributing to OME (contributing:ome)= diff --git a/contributing/specification/index.md b/contributing/specification/index.md new file mode 100644 index 00000000..46ab875f --- /dev/null +++ b/contributing/specification/index.md @@ -0,0 +1,164 @@ +# Changes to the specification +(contributing:spec)= + +Any suggested major changes to the `OME-Zarr` specification should be opened as +request for comment (RFC) documents. + +In the future we will flesh out this page with a guide to RFCs, but in the +meantime the RFC process is outlined in the +[Implementation section of RFC 1](../rfc/1/index.md#implementation). + +## Comment on a Request For Comment (RFC) + +If you want to leave a suggestion or comment on an RFC that is under review, +please leave a comment in a new page under the "comments/" directory for the +relevant RFC. A template is also available for formatting your comment: +[template](../rfc/1/templates/review_template). + +## How to change the specification + +To make a change such as the end-product of an RFC or a minor correction to the currently developed specification version, +please do so via a pull request (PR) against the `main` branch of the [ome/ngff-spec](https://github.com/ome/ngff-spec) repository. +Such a PR can contain a change of any of the following components of the ngff-spec repo: + +- The spec text itself (`ngff-spec/inex.md`) +- The schemas (`ngff-spec/schemas/`) +- Example json metadata (`ngff-spec/examples/`) + +## Author guidelines + +This repository uses Sphinx to publish a ReadTheDocs site at https://ngff.openmicroscopy.org in the [Pydata Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/). +[MyST](https://myst-parser.readthedocs.io/en/latest/) syntax can be used in addition to basic Markdown and HTML. + +Many flavors of markdown exist. I.e., the ngff-spec page uses [Jupyter Book](https://jupyterbook.org) and the ngff website (this page) uses [Sphinx](https://www.sphinx-doc.org/en/master/). +To make sure that all used markdown stylings and syntax styles are compatible, +please find below a few guidelines for writing markdown in the [ngff-spec](https://github.com/ome/ngff-spec) repository. + +```{note} +Please don't let *I don't understand the markdown syntax* stop you from contributing! +If you have a suggestion for a change to the website or specification but are not sure how to write it in markdown, +please just write it in plain markdown and we can help you with the formatting. +``` + +### Text format + +Contributions should conform to [Semantic Line Breaks (SemBr)](https://sembr.org/), +to improve change tracking. + +### Referencing + +The specification uses [MyST](https://mystmd.org) extensively for a number of formatting options +to make the text readable and improve structure. + +MyST allows a number of ways to reference and cross-reference inside this text +and across several of the pages in this repo. +For an overview of supported referencing syntax, +see the [MyST doc pages](https://mystmd.org/guide/cross-references). +It is recommended to use the following syntax in this document for consistency: + +```markdown +anchor: (your-reference-name)= +reference: [This is a reference](#your-reference-name) +``` + +This way, your cross-references will always resolve to the correct page, +even if the location of the markdown file changes in the future. + +For cross-referencing in the spec document, +make sure to prepend the reference anchor with `versionX` like so: + +```markdown +## Some header +(version0.9:some-header)= +``` + +Otherwise, the same anchors may not be possible to resolve +if multiple versions of the spec document are built and viewed together (i.e., the anchor `(ngff-spec: some_anchor)` may exist in multiple documents). + +### Highlighting + +If you refer to fields or values that would appear in JSON files, +please use backticks to highlight them, like so: + +```markdown +The `multiscales` field contains an array of dictionaries. +``` + +You may still use bold, italics or quotation marks for emphasis where appropriate, +but please use backticks for JSON fields and values. + +### Citations + +ngff-spec relies on [sphinxcontrib-bibtex](https://pypi.org/project/sphinxcontrib-bibtex/) for citations. +To add a citation to the text, add it as a bibtex entry in the `references.bib` file in the root of this repository. +You can then cite it in the text using the following syntax: + +```markdown +This is a citation {cite:t}`citation_key`. +``` + +where `citation_key` is the key of the bibtex entry in the `references.bib` file. + +### Json examples + +We suggest using [dropdowns](https://mystmd.org/guide/dropdowns-cards-and-tabs) for example code and other highlighting. +For examples, please use the following syntax to wrap your examples: + +`````markdown +:::{dropdown} Example + +Some informative text about your example +```json +"key": "value" +``` +::: +````` + +which results in + +:::{dropdown} Example + +Some informative text about your example +```json +"key": "value" +``` +::: + +If you want to link in example metadata from somewhere in this repo (i.e, a json file), +use this syntax: + +`````markdown +:::dropdown Example + +Some informative text about your example +```{literalinclude} path/to/example.json +:language: json +:linenos: +:tab-width: 2 +``` +::: +````` + +Other useful admonitions and directives (e.g., `hint`, `note`) can be found [here](https://mystmd.org/guide/directives). + +## Building *only* the spec document + +The spec document under the [ngff-spec](github.com/ome/ngff-spec) repository can be built as a standalone document to make writing and rendering a smoother experience. +To build the spec document, you first need to install the necessary dependencies: + +After cloning the ngff-spec repo, navigate into the repository on your machine and install the dependencies using pip: + +```bash +cd path/to/ngff-spec +pip install -e . +``` + +This document uses [jupyter-book](https://jupyterbook.org) to generate the pages +and [MyST](https://mystmd.org) markdown for formatting. +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 # auto-generates some of the markdown files (examples, schemas) +jupyter book start # start a local server to view the book +``` \ No newline at end of file diff --git a/contributing/website/index.md b/contributing/website/index.md new file mode 100644 index 00000000..8963f33d --- /dev/null +++ b/contributing/website/index.md @@ -0,0 +1,42 @@ +# Changes to this website + +The repository for this website is [ome/ngff](https://github.com/ome/ngff). +Contributions to these pages are welcome as issues or PRs. + +To do so, create a fork of the ``ome/ngff`` repository, make your changes, +and submit a pull request (PR) against the `main` branch. + +## Configuration +Edit [conf.py](https://github.com/ome/ngff/blob/main/conf.py) with options from the [PyData Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/). The [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/index.html) user guide may also have more up to date instructions for configuration properties. + +## Building the pages locally + +Before submitting changes to the ngff website, +please build the pages locally and make sure that everything renders correctly. + +To do so, first install a few necessary (Python) dependencies: + +```bash +cd path/to/ngff/repo +pip install -r requirements.txt +pip install specifications/dev +``` + +Then, you can build the pages locally with: + +```bash +make html +``` + +or + +```bash +python conf.py +``` + +You can then find the rendered pages under `_build/html/index.html`. + +## Previews +Each PR receives a unique preview URL of the format `https://ngff--.org.readthedocs.build/` where `` is the PR number. This link is also posted to each PR by the Github actions bot in an "Automated Review URLs" comment as the "Readthedocs" link. + +Please check that your changes render correctly at this URL. New commits will automatically be live at the PR url after a few minutes. \ No newline at end of file From 69ae40db44087d1c37c60f9855ead7b5a7d2de80 Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Mon, 16 Feb 2026 11:20:50 +0100 Subject: [PATCH 2/3] correct bash syntax --- contributing/specification/index.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/contributing/specification/index.md b/contributing/specification/index.md index 46ab875f..c4ffdcc3 100644 --- a/contributing/specification/index.md +++ b/contributing/specification/index.md @@ -159,6 +159,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 # auto-generates some of the markdown files (examples, schemas) -jupyter book start # start a local server to view the book -``` \ No newline at end of file +python pre_build.py +jupyter book start +``` + +This autogenerates some of the markdown files (examples, schemas) and starts a local server to view the book. \ No newline at end of file From db33884cf4fa91d5f9450ff6f58b800f1606d6c8 Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Fri, 13 Mar 2026 09:39:44 +0100 Subject: [PATCH 3/3] chore: fix typo --- contributing/specification/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/specification/index.md b/contributing/specification/index.md index c4ffdcc3..ca262d33 100644 --- a/contributing/specification/index.md +++ b/contributing/specification/index.md @@ -21,7 +21,7 @@ To make a change such as the end-product of an RFC or a minor correction to the please do so via a pull request (PR) against the `main` branch of the [ome/ngff-spec](https://github.com/ome/ngff-spec) repository. Such a PR can contain a change of any of the following components of the ngff-spec repo: -- The spec text itself (`ngff-spec/inex.md`) +- The spec text itself (`ngff-spec/index.md`) - The schemas (`ngff-spec/schemas/`) - Example json metadata (`ngff-spec/examples/`)