Configure joint webpage layout for spec/examples/schemas

.gitignore

@@ -0,0 +1,97 @@
+*/.DS_Store
+**/__pycache__/*
+*/index.html
+_build
+_bikeshed
+.tox
+.vscode
+.*plist
+
+# do not sync auto-generated md files
+docs/examples/
+docs/schemas/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+*_version.py
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+.napari_cache
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask instance folder
+instance/
+
+# Sphinx documentation
+docs/_build/
+
+# MkDocs documentation
+/site/
+
+# PyBuilder
+target/
+
+# IPython Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# OS
+.DS_Store
+
+# written by setuptools_scm
+*/_version.py
+
+# PyBuilder
+.idea
+venv/

.readthedocs.yaml

@@ -0,0 +1,19 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+  jobs:
+    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
+
+
+sphinx:
+  configuration: conf.py

_config.yml

@@ -0,0 +1,83 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+# Comprehensive example: https://github.com/executablebooks/jupyter-book/blob/master/docs/_config.yml
+
+title: Next-generation file format specification
+author: NGFF-community
+logo: https://www.openmicroscopy.org/img/logos/ome-logomark.svg
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+# execute:
+#   execute_notebooks: off
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+ - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/ome/ngff-spec  # Online location of your book
+  path_to_book: docs  # Optional path to your book, relative to the repository root
+  branch: main  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+  extra_footer: |
+      <div>
+        Copyright © 2020-<span id="current-year"></span>
+        <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>).
+        OME trademark rules apply.
+      </div>
+      <script>
+        document.getElementById('current-year').textContent = new Date().getFullYear();
+      </script>
+
+parse:
+  myst_heading_anchors: 3
+
+myst:
+  enable_extensions:
+    - colon_fence
+    - deflist
+    - dollarmath
+    - linkify
+    - substitution
+
+
+sphinx:
+  extra_extensions:
+    - sphinx.ext.autosummary
+    - sphinx.ext.autodoc
+    - sphinx.ext.napoleon # Enable support for NumPy and Google style docstrings
+    - sphinx.ext.intersphinx
+    - sphinx_inline_tabs
+    - sphinx_proof
+    - sphinx_examples
+  config:
+    html_show_copyright: false
+    add_module_names: True
+    autosummary_generate: True
+
+    myst_substitutions:
+      title: "OME-Zarr specification"
+      shortname: "ome-zarr"
+      level: "1"
+      status: "CG-FINAL"
+      tr_url: "https://ngff.openmicroscopy.org/0.5/"
+      url: "https://ngff.openmicroscopy.org/0.6-dev/"
+      issue_tracking: "[Forum](https://forum.image.sc/tag/ome-ngff), [Github](https://github.com/ome/ngff/issues)"
+      logo: "http://www.openmicroscopy.org/img/logos/ome-logomark.svg"
+      editor_name: "[Josh Moore](https://gerbi-gmb.de/)"
+      editor_affiliation: "German BioImaging e.V."
+      editor_orcid: "[https://orcid.org/0000-0003-4028-811X](https://orcid.org/0000-0003-4028-811X)"
+      version: "0.6.dev1"

_toc.yml

@@ -0,0 +1,17 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: specification
+
+chapters:
+- file: docs/examples
+  sections:
+  - glob: docs/examples/*
+- file: docs/schemas/index
+  sections:
+  - glob: docs/schemas/markdown/*
+
+- file: contribute
+- file: citing
+- file: version_history

citing.md

@@ -0,0 +1,13 @@
+Citing
+======
+(citing)=
+
+[Next-generation file format (NGFF) specifications for storing bioimaging data in the cloud.](https://ngff.openmicroscopy.org/0.4)
+J. Moore, *et al*. Open Microscopy Environment Consortium, 8 February 2022.
+
+This edition of the specification is [https://ngff.openmicroscopy.org/{{version}}](https://ngff.openmicroscopy.org/{{version}}]).
+The latest edition is publically available {cite}`ngff_spec_latest`.
+
+```{bibliography}
+:style: unsrt
+```

contribute.md

@@ -0,0 +1,83 @@
+# Contribution guide
+
+Contributions to the spec text, examples and schemas are highly welcome and
+appreciated by the ngff community. If you propose an RFC (i.e., major change)
+or a aminor change (pull request), please make sure to follow [these guidelines](https://ngff.openmicroscopy.org/contributing/index.html).
+
+Major changes should follow the RFC process as it was laid out in [RFC1 ](https://ngff.openmicroscopy.org/rfc/1/index.html).
+
+## Building the documentation
+
+Build and inspect changes to the documentation before submitting a PR. To do so, you first need
+to install the necessary dependecies:
+
+```bash
+pip install -r docs/requirements.txt
+```
+
+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 docs/pre_build.py
+jupyter-book build . --path-output docs
+```
+
+You'll find the built webpages under `docs/_build/html`.
+
+### Formating hints
+
+The specification uses MyST extensively for a number of formatting options to make the text
+readible and improve structure.
+
+#### Referencing
+
+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 consitency:
+```
+anchor: (your-reference-name)=
+reference: [This is a reference](your-reference-name)
+```
+
+#### Admonitions
+
+We suggest using [admonitions](https://mystmd.org/guide/admonitions) for example code and
+other highlighting. For examples, please use the following syntax to highlight your examples:
+
+`````markdown
+````{admonition} Example
+
+Some informative text about your example
+```json
+"key": "value"
+```
+````
+`````
+
+which results in 
+
+````{admonition} 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
+````{admonition} Example
+
+Some informative text about your example
+```{literalinclude} path/to/example.json
+:language: json
+```
+````
+`````
+
+Other useful admonitions (e.g., `hint`, `note`) can be found [here](https://mystmd.org/guide/directives)

docs/examples.md

@@ -0,0 +1,3 @@
+# JSON Examples
+
+This document contains JSON examples for ngff-compliant metadata layouts.