Merge branch 'splash-ngff_spec' into fix-version-parsing

jo-mueller · web-flow · commit 9c14f740e83d · 2025-12-15T14:21:45.000+01:00
diff --git a/.gitignore b/.gitignore
@@ -38,7 +38,6 @@ var/
 *.egg-info/
 .installed.cfg
 *.egg
-*_version.py
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -91,9 +90,6 @@ target/
 # OS
 .DS_Store
 
-# written by setuptools_scm
-*/_version.py
-
 # PyBuilder
 .idea
 venv/
diff --git a/ngff_spec/CITATION.cff b/ngff_spec/CITATION.cff
@@ -0,0 +1,88 @@
+cff-version: 1.2.0
+message: Please cite the following works when using this project.
+abstract: >-
+  A growing community is constructing a next-generation file format (NGFF) for
+  bioimaging to overcome problems of scalability and heterogeneity. Organized by
+  the Open Microscopy Environment (OME), individuals and institutes across
+  diverse modalities facing these problems have designed a format specification
+  process (OME-NGFF) to address these needs. Those community members have built
+  the format itself – OME-Zarr – along with tools and data resources available
+  today to increase FAIR access and remove barriers in the scientific process.
+  The current momentum offers an opportunity to unify a key component of the
+  bioimaging domain — the file format that underlies so many personal,
+  institutional, and global data management and analysis tasks.
+title: Next-generation file format specification
+authors:
+  - family-names: NGFF-community
+    given-names: ''
+identifiers:
+  - type: doi
+    value: 10.1038/s41592-021-01326-w
+    description: Original Nature Methods article (2021)
+  - type: doi
+    value: 10.1101/2023.02.17.528834v2
+    description: OME-Zarr preprint (2023)
+keywords:
+  - FAIR
+  - community
+  - bioimaging
+  - data
+  - cloud
+  - format
+license: CC-BY-4.0
+url: https://ngff.openmicroscopy.org
+repository: https://github.com/ome/ngff-spec
+preferred-citation:
+  type: article
+  doi: 10.1038/s41592-021-01326-w
+  journal: Nature Methods
+  month: 11
+  start: 1496
+  end: 1498
+  title: >-
+    OME-NGFF: a next-generation file format for expanding bioimaging data-access
+    strategies
+  issue: 12
+  volume: 18
+  year: 2021
+  authors:
+    - given-names: Josh
+      family-names: Moore
+      orcid: https://orcid.org/0000-0003-4028-811X
+    - given-names: Chris
+      family-names: Allan
+    - given-names: Sébastien
+      family-names: Besson
+      orcid: https://orcid.org/0000-0001-8783-1429
+    - given-names: Jean-Marie
+      family-names: Burel
+      orcid: https://orcid.org/0000-0002-1789-1861
+    - given-names: Erin
+      family-names: Diel
+      orcid: https://orcid.org/0000-0003-2526-3512
+    - given-names: David
+      family-names: Gault
+    - given-names: Kevin
+      family-names: Kozlowski
+    - given-names: Dominik
+      family-names: Lindner
+      orcid: https://orcid.org/0000-0001-8038-1250
+    - given-names: Melissa
+      family-names: Linkert
+    - given-names: Trevor
+      family-names: Manz
+      orcid: https://orcid.org/0000-0001-7694-5164
+    - given-names: Will
+      family-names: Moore
+      orcid: https://orcid.org/0000-0002-7264-8338
+    - given-names: Constantin
+      family-names: Pape
+      orcid: https://orcid.org/0000-0001-6562-7187
+    - given-names: Christian
+      family-names: Tischer
+      orcid: https://orcid.org/0000-0003-4105-1990
+    - given-names: Jason R.
+      family-names: Swedlow
+      orcid: https://orcid.org/0000-0002-2198-1958
+type: software
+repository-code: https://github.com/ome/ngff
diff --git a/ngff_spec/_version.py b/ngff_spec/_version.py
@@ -0,0 +1 @@
+__version__ = '0.6.dev1'
diff --git a/ngff_spec/citing.md b/ngff_spec/citing.md
@@ -1,5 +1,7 @@
-Citing
-======
+---
+title: Citing
+author: ""
+---
 (citing)=
 
 [Next-generation file format (NGFF) specifications for storing bioimaging data in the cloud.](https://ngff.openmicroscopy.org/0.4)
diff --git a/ngff_spec/contribute.md b/ngff_spec/contribute.md
@@ -1,3 +1,6 @@
+---
+author: ""
+---
 # Contribution guide
 
 Contributions to the spec text, examples and schemas are highly welcome
@@ -28,6 +31,39 @@ jupyter book build ngff_spec
 
 You'll find the built webpages under `_build/html`.
 
+## First contribution
+
+If you haven't contributed to the spec before,
+please add yourself as an author in the `ngff_spec/myst.yml` metadata file.
+This should look like this, for example:
+
+```yaml
+    - name: John A. Doe
+      id: jdoe
+      orcid: xxxx-xxxx-xxxx-xxxx
+      github: jdoe
+      affiliations:
+        - id: key
+          institution: ICSLDJ University
+          city: Doeburg
+          ror: https://ror.org/....
+    - name: Jane Doe
+      affiliations: key
+```
+
+For more information see [myst documentation on author formatting](https://mystmd.org/guide/frontmatter#frontmatter-authors).
+
+When you submit your first PR,
+make sure to rebuild the `CITATION.cff` file in the root of this repository.
+To do so, run the following command:
+
+```bash
+cd ngff_spec/ && jupyter book build --cff
+```
+
+Copy the generated `CITATION.cff` file from `ngff_spec/CITATION.cff` to the root of this repository
+and submit it along with your PR.
+
 ### Text format
 
 Contributions should conform to [Semantic Line Breaks (SemBr)](https://sembr.org/),
diff --git a/ngff_spec/myst.yml b/ngff_spec/myst.yml
@@ -10,12 +10,96 @@ project:
     - format: pdf
       template: plain_latex_book
       output: exports/book.pdf
+    - format: cff
+      type: software
+      identifiers:
+        - type: doi
+          value: 10.1038/s41592-021-01326-w
+          description: Original Nature Methods article (2021)
+        - type: doi
+          value: 10.1101/2023.02.17.528834v2
+          description: OME-Zarr preprint (2023)
+      repository-code: 'https://github.com/ome/ngff'
+      url: 'https://ngff.openmicroscopy.org'
+      abstract: >-
+        A growing community is constructing a next-generation file
+        format (NGFF) for bioimaging to overcome problems of
+        scalability and heterogeneity. Organized by the Open
+        Microscopy Environment (OME), individuals and institutes
+        across diverse modalities facing these problems have
+        designed a format specification process (OME-NGFF) to
+        address these needs. Those community members have built
+        the format itself – OME-Zarr – along with tools and data
+        resources available today to increase FAIR access and
+        remove barriers in the scientific process. The current
+        momentum offers an opportunity to unify a key component of
+        the bioimaging domain — the file format that underlies so
+        many personal, institutional, and global data management
+        and analysis tasks.
+      keywords:
+        - FAIR
+        - community
+        - bioimaging
+        - data
+        - cloud
+        - format
+      license: CC-BY-4.0
+      preferred-citation:
+        type: article
+        doi: "10.1038/s41592-021-01326-w"
+        journal: "Nature Methods"
+        month: 11
+        start: 1496
+        end: 1498
+        title: "OME-NGFF: a next-generation file format for expanding bioimaging data-access strategies"
+        issue: 12
+        volume: 18
+        year: 2021
+        authors:
+        - given-names: "Josh"
+          family-names: "Moore"
+          orcid: "https://orcid.org/0000-0003-4028-811X"
+        - given-names: "Chris"
+          family-names: "Allan"
+        - given-names: "Sébastien"
+          family-names: "Besson"
+          orcid: "https://orcid.org/0000-0001-8783-1429"
+        - given-names: "Jean-Marie"
+          family-names: "Burel"
+          orcid: "https://orcid.org/0000-0002-1789-1861"
+        - given-names: "Erin"
+          family-names: "Diel"
+          orcid: "https://orcid.org/0000-0003-2526-3512"
+        - given-names: "David"
+          family-names: "Gault"
+        - given-names: "Kevin"
+          family-names: "Kozlowski"
+        - given-names: "Dominik"
+          family-names: "Lindner"
+          orcid: "https://orcid.org/0000-0001-8038-1250"
+        - given-names: "Melissa"
+          family-names: "Linkert"
+        - given-names: "Trevor"
+          family-names: "Manz"
+          orcid: "https://orcid.org/0000-0001-7694-5164"
+        - given-names: "Will"
+          family-names: "Moore"
+          orcid: "https://orcid.org/0000-0002-7264-8338"
+        - given-names: "Constantin"
+          family-names: "Pape"
+          orcid: "https://orcid.org/0000-0001-6562-7187"
+        - given-names: "Christian"
+          family-names: "Tischer"
+          orcid: "https://orcid.org/0000-0003-4105-1990"
+        - given-names: "Jason R."
+          family-names: "Swedlow"
+          orcid: "https://orcid.org/0000-0002-2198-1958"
   toc:
     - file: specification.md
-    - file: examples.md
+    - file: _generated/examples.md
       children:
         - pattern: _generated/examples/*
-    - file: schemas.md
+    - file: _generated/schemas.md
       children:
         - pattern: _generated/schemas/markdown/*
     - file: contribute.md
diff --git a/ngff_spec/pre_build.py b/ngff_spec/pre_build.py
@@ -23,19 +23,22 @@ def build_json_examples():
     index_md = """---
 title: NGFF metadata JSON Examples
 short_title: JSON Examples
+author: ""
 ---
 
 This section contains JSON examples for various metadata layouts.
 """
 
     for example in example_types:
         json_files = glob.glob(os.path.join(input_directory, example, '*.json'), recursive=True)
-        markdown_file_name = os.path.join(output_directory, f'{example}.md')
 
         index_md += f"\n## {example}\n"
 
         # add header
-        markdown_content = f"""# {example}\n\n
+        markdown_content = f"""---
+title: {example} Examples
+author: ""
+---
 
 This document contains JSON examples for {example} metadata layouts.
 
@@ -62,10 +65,10 @@ def build_json_examples():
 ```
 """
         # create 
-        with open(markdown_file_name, 'w') as md_file:
+        with open(os.path.join(output_directory, f'{example}.md'), 'w') as md_file:
             md_file.write(markdown_content)
 
-    with open(os.path.join("examples.md"), 'w') as index_file:
+    with open(os.path.join("_generated/examples.md"), 'w') as index_file:
         index_file.write(index_md)
 
 def build_json_schemas():
@@ -78,15 +81,12 @@ def build_json_schemas():
     os.makedirs(output_directory, exist_ok=True)
     schema_files = glob.glob(os.path.join(schema_source_dir, '*.schema'), recursive=True)
 
-    # Create a resolver mapping for local schemas
-    schema_mapping = {}
-    for schema_file in schema_files:
-        with open(schema_file, 'r') as f:
-            schema_content = json.load(f)
-            if '$id' in schema_content:
-                schema_mapping[schema_content['$id']] = os.path.abspath(schema_file)
 
-    index_markdown = """# JSON Schemas
+    index_markdown = """---
+title: NGFF metadata JSON Schemas
+short_title: JSON Schemas
+author: ""
+---
 
 This section contains JSON schemas for various metadata layouts.
 Find below links to auto-generated markdown pages or interactive HTML pages for each schema.
@@ -110,34 +110,39 @@ def build_json_schemas():
             config_md = GenerationConfiguration(
                 template_name='md',
                 with_footer=True,
-                show_toc=False,
-                link_to_reused_ref=False,
-                custom_template_global_vars={'schema_mapping': schema_mapping})
+                show_toc=True,
+                link_to_reused_ref=True,
+                )
             generate_from_filename(
                 os.path.abspath(schema_file),
                 result_file_name=os.path.abspath(output_path_md),
                 config=config_md
             )
 
             # insert mySt cross-reference at top of markdown files
-            with open(output_path_md, 'r') as md_file:
+            with open(output_path_md, 'r', encoding='utf-8') as md_file:
                 md_content = md_file.read()
             crossref = f"schemas:{Path(schema_file).stem}"
-            md_content = f"({crossref})=\n\n{md_content}"
-            with open(output_path_md, 'w') as md_file:
+            md_content = f"""---
+author: ""
+---
+({crossref})=\n\n{md_content}
+"""
+            with open(output_path_md, 'w', encoding='utf-8') as md_file:
                 md_file.write(md_content)
 
             link_markdown = f"[{Path(schema_file).stem}](#{crossref})"
-        except Exception:
+        except Exception as e:
+            print(f"Error generating markdown for {schema_file}: {e}")
             link_markdown = ""
 
         try:
             config_html = GenerationConfiguration(
                 template_name='js',
                 with_footer=True,
                 show_toc=False,
-                link_to_reused_ref=False,
-                custom_template_global_vars={'schema_mapping': schema_mapping})
+                link_to_reused_ref=True,
+                )
 
             generate_from_filename(
                 os.path.abspath(schema_file),
@@ -146,12 +151,13 @@ def build_json_schemas():
             )
             link_html = f"[{Path(schema_file).stem}]({output_path_html})"
 
-        except Exception:
+        except Exception as e:
+            print(f"Error generating HTML for {schema_file}: {e}")
             link_html = ""
 
         index_markdown += f"| {Path(schema_file).stem} | {link_markdown} | {link_html} |\n"
 
-    with open(os.path.join("schemas.md"), 'w') as index_file:
+    with open(os.path.join("_generated/schemas.md"), 'w') as index_file:
         index_file.write(index_markdown)
 
 def build_footer():
@@ -161,8 +167,7 @@ def build_footer():
     footer_content = f"""
 <div>
     Copyright © 2020-{year}
-    <a href="https://www.openmicroscopy.org/"><abbr title="Open Microscopy Environment">OME</abbr></a><sup>®</sup>
-    (<a href="https://dundee.ac.uk/"><abbr title="University of Dundee">U. Dundee</abbr></a>).
+    <a href="https://www.openmicroscopy.org/"><abbr title="Open Microscopy Environment">OME</abbr></a><sup>®</sup>.
     OME trademark rules apply.
 </div>
 """
diff --git a/ngff_spec/version_history.md b/ngff_spec/version_history.md
diff --git a/pyproject.toml b/pyproject.toml
