Simpler build

.gitignore

@@ -1,7 +1,7 @@
 *.DS_Store
 **/__pycache__/*
 */index.html
-_tmp_ngff_spec/
+_temp_ngff_spec/
 _build
 _html_extra
 .tox

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)
 
@@ -163,6 +167,14 @@ 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}. "
+                "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
         ]

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/<your-username>/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:

requirements.txt

@@ -2,6 +2,7 @@ bikeshed
 myst-parser
 pydata-sphinx-theme
 json-schema-for-humans
+json-with-comments
 testresources
 sphinx-reredirects
 sphinxcontrib-bibtex