From 4cf90f8139fa675f66a7345410e868a0b338e7ed Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Tue, 10 Nov 2026 11:16:55 +0100 Subject: [PATCH 1/3] feat: make page build stable against existence of submodules --- .gitignore | 2 +- conf.py | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 4f7cd959f..c497a769d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ *.DS_Store **/__pycache__/* */index.html -_tmp_ngff_spec/ +_temp_ngff_spec/ _build _html_extra .tox diff --git a/conf.py b/conf.py index f39f70cde..47655c0e6 100644 --- a/conf.py +++ b/conf.py @@ -163,6 +163,10 @@ def build_served_html(clean_up=True): for version in displayed_spec_versions: # find 'pre_build.py' in 'specifications' subdirectories + # skip if submodule hasn't been checked out. + if len(os.listdir(f"specifications/{version}")) == 0: + print(f"⚠️ No files found for version {version}") + continue script = glob.glob(f"specifications/{version}/**/pre_build.py", recursive=True)[ 0 ] From 4f5912af94c969d080c881fe13282a17a203c443 Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Tue, 10 Nov 2026 14:29:57 +0100 Subject: [PATCH 2/3] feat: simplify build process --- conf.py | 6 +++++- contributing/website/index.md | 26 +++++++++++++++++--------- requirements.txt | 1 + 3 files changed, 23 insertions(+), 10 deletions(-) diff --git a/conf.py b/conf.py index 47655c0e6..d2c83c197 100644 --- a/conf.py +++ b/conf.py @@ -113,7 +113,11 @@ def build_served_html(clean_up=True): from pathlib import Path os.chdir(Path(__file__).parent) - + + # Keep specifications/* submodules in sync regardless of entry point + # (make, make.bat, sphinx-autobuild all import this file). + subprocess.check_call(["git", "submodule", "update", "--init", "--depth", "1"]) + # Create .htaccess to serve schemas inline (not download) os.makedirs("_html_extra", exist_ok=True) diff --git a/contributing/website/index.md b/contributing/website/index.md index 08b51d04c..092e29167 100644 --- a/contributing/website/index.md +++ b/contributing/website/index.md @@ -6,20 +6,19 @@ 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. -## Setting up the repository -Create a fork of the ``ome/ngff`` repository. - -When cloning your fork locally, you will need to pull the submodules in `specifications/`: -```bash -git submodule init -git submodule update -``` - ## 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 +Create a fork of the ``ome/ngff`` repository. +Then. clone the forked repository to your local machine. + +```bash +git clone https://github.com//ngff.git +cd ngff +``` + Before submitting changes to the ngff website, please build the pages locally and make sure that everything renders correctly. @@ -32,9 +31,18 @@ pip install specifications/dev ``` Then, you can build the pages locally with: +::::{tab-set} +:::{tab-item} Windows +```bash +.\make html +``` +::: +:::{tab-item} Linux ```bash make html ``` +::: +:::: You can then find the rendered pages under `_build/html/index.html`. Alternatively, to build and preview the pages locally: diff --git a/requirements.txt b/requirements.txt index 743590fa3..18f8e8cac 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,6 +2,7 @@ bikeshed myst-parser pydata-sphinx-theme json-schema-for-humans +json-with-comments testresources sphinx-reredirects sphinxcontrib-bibtex From e48ed65701a0cd968408d7d05022ec4b74cc1951 Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Wed, 11 Nov 2026 07:57:44 +0100 Subject: [PATCH 3/3] feat: More informative error message --- conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index d2c83c197..9056b4074 100644 --- a/conf.py +++ b/conf.py @@ -169,7 +169,11 @@ def build_served_html(clean_up=True): # find 'pre_build.py' in 'specifications' subdirectories # skip if submodule hasn't been checked out. if len(os.listdir(f"specifications/{version}")) == 0: - print(f"⚠️ No files found for version {version}") + print( + f"⚠️ No files found for version {version}. " + "This indicates missing specification files or git submodules. " + "See https://ngff.openmicroscopy.org/contributing/website for help in debugging the build." + ) continue script = glob.glob(f"specifications/{version}/**/pre_build.py", recursive=True)[ 0