From 85a550b7049852864b5eb6b5e22da0f6b0c94b47 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Fri, 14 Aug 2026 23:48:44 +0200
Subject: [PATCH 1/6] feat: find all tagged versions and serve schemas directly
from gh
---
conf.py | 32 +++++++++++++++++++++++---------
1 file changed, 23 insertions(+), 9 deletions(-)
diff --git a/conf.py b/conf.py
index 55152f5e..29e5f5e8 100644
--- a/conf.py
+++ b/conf.py
@@ -57,6 +57,25 @@
"dev/": "../specifications/dev/index.html",
}
+# Populate schema redirects from GitHub tags
+def _populate_schema_redirects():
+ import subprocess
+ result = subprocess.check_output([
+ "git", "ls-remote", "--tags", "https://github.com/ome/ngff-spec"
+ ], text=True, timeout=10)
+ # result looks like this
+ # e3d2f8ffbbcfb0e0906e901ec572f5c49b36328d refs/tags/0.6.dev1
+ # da4606bf96d2829ad74b4dbaf6de5afb6b7a595a refs/tags/0.6.dev2
+
+ tags = [
+ line.split()[1].replace("refs/tags/", "").rstrip("^{}")
+ for line in result.strip().split("\n") if line
+ ]
+ for tag in sorted(set(tags)):
+ redirects[f"{tag}/schemas/"] = f"https://raw.githubusercontent.com/ome/ngff-spec/{tag}/schemas/"
+
+_populate_schema_redirects()
+
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -102,20 +121,15 @@ def build_served_html():
from pathlib import Path
os.chdir(Path(__file__).parent)
- versions = [
+
+ # Build specifications from local submodules
+ displayed_spec_versions = [
d
for d in os.listdir("specifications")
if os.path.isdir(os.path.join("specifications", d))
]
- for version in versions:
-
- # copy schemas to _html_extra
- os.makedirs(f"_html_extra/{version}/schemas", exist_ok=True)
- schemas = glob.glob(f"specifications/{version}/**/*.schema", recursive=True)
- for schema in schemas:
- shutil.copy2(schema, f"_html_extra/{version}/schemas/")
- print(f"✅ Copied schemas for version {version}")
+ for version in displayed_spec_versions:
# find 'pre_build.py' in 'specifications' subdirectories
script = glob.glob(f"specifications/{version}/**/pre_build.py", recursive=True)[
From 598c9965af735902102b837ded125296e6ab7970 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Sat, 15 Aug 2026 00:00:23 +0200
Subject: [PATCH 2/6] feat: serve extra html with redirect info
---
conf.py | 33 ++++++++++++++-------------------
1 file changed, 14 insertions(+), 19 deletions(-)
diff --git a/conf.py b/conf.py
index 29e5f5e8..f4affd17 100644
--- a/conf.py
+++ b/conf.py
@@ -57,25 +57,6 @@
"dev/": "../specifications/dev/index.html",
}
-# Populate schema redirects from GitHub tags
-def _populate_schema_redirects():
- import subprocess
- result = subprocess.check_output([
- "git", "ls-remote", "--tags", "https://github.com/ome/ngff-spec"
- ], text=True, timeout=10)
- # result looks like this
- # e3d2f8ffbbcfb0e0906e901ec572f5c49b36328d refs/tags/0.6.dev1
- # da4606bf96d2829ad74b4dbaf6de5afb6b7a595a refs/tags/0.6.dev2
-
- tags = [
- line.split()[1].replace("refs/tags/", "").rstrip("^{}")
- for line in result.strip().split("\n") if line
- ]
- for tag in sorted(set(tags)):
- redirects[f"{tag}/schemas/"] = f"https://raw.githubusercontent.com/ome/ngff-spec/{tag}/schemas/"
-
-_populate_schema_redirects()
-
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -122,6 +103,20 @@ def build_served_html():
os.chdir(Path(__file__).parent)
+ # Fetch GitHub tags and create schema redirects
+ try:
+ result = subprocess.check_output([
+ "git", "ls-remote", "--tags", "https://github.com/ome/ngff-spec"
+ ], text=True, timeout=10)
+ tags = [line.split()[1].replace("refs/tags/", "").rstrip("^{}") for line in result.strip().split("\n") if line]
+ for tag in sorted(set(tags)):
+ os.makedirs(f"_html_extra/{tag}/schemas", exist_ok=True)
+ with open(f"_html_extra/{tag}/schemas/index.html", "w") as f:
+ f.write(f'')
+ print(f"✅ Redirect schemas/{tag} → GitHub raw")
+ except Exception:
+ pass
+
# Build specifications from local submodules
displayed_spec_versions = [
d
From 0369fa2b366eed4ba9d0c6650640ecb28a9640c8 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Sat, 15 Aug 2026 00:12:47 +0200
Subject: [PATCH 3/6] feat: try .htaccess file
---
conf.py | 21 ++++++++-------------
1 file changed, 8 insertions(+), 13 deletions(-)
diff --git a/conf.py b/conf.py
index f4affd17..6d413aab 100644
--- a/conf.py
+++ b/conf.py
@@ -103,19 +103,14 @@ def build_served_html():
os.chdir(Path(__file__).parent)
- # Fetch GitHub tags and create schema redirects
- try:
- result = subprocess.check_output([
- "git", "ls-remote", "--tags", "https://github.com/ome/ngff-spec"
- ], text=True, timeout=10)
- tags = [line.split()[1].replace("refs/tags/", "").rstrip("^{}") for line in result.strip().split("\n") if line]
- for tag in sorted(set(tags)):
- os.makedirs(f"_html_extra/{tag}/schemas", exist_ok=True)
- with open(f"_html_extra/{tag}/schemas/index.html", "w") as f:
- f.write(f'')
- print(f"✅ Redirect schemas/{tag} → GitHub raw")
- except Exception:
- pass
+ # Create .htaccess to redirect all schema requests to GitHub
+ # ponytail: one rewrite rule handles all versions/files, avoids generating per-file stubs
+ htaccess_content = """RewriteEngine On
+RewriteRule ^([^/]+)/schemas/(.*)$ https://raw.githubusercontent.com/ome/ngff-spec/$1/schemas/$2 [R=301,L]
+"""
+ with open("_html_extra/.htaccess", "w") as f:
+ f.write(htaccess_content)
+ print(f"✅ Created .htaccess redirect for all schemas → GitHub raw")
# Build specifications from local submodules
displayed_spec_versions = [
From 061c07e46d5a589f9e3a1f9d8cc142ddef4db1eb Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Sat, 15 Aug 2026 00:15:46 +0200
Subject: [PATCH 4/6] fix: create _html_extra
---
conf.py | 1 +
1 file changed, 1 insertion(+)
diff --git a/conf.py b/conf.py
index 6d413aab..c0a737c3 100644
--- a/conf.py
+++ b/conf.py
@@ -105,6 +105,7 @@ def build_served_html():
# Create .htaccess to redirect all schema requests to GitHub
# ponytail: one rewrite rule handles all versions/files, avoids generating per-file stubs
+ os.makedirs("_html_extra", exist_ok=True)
htaccess_content = """RewriteEngine On
RewriteRule ^([^/]+)/schemas/(.*)$ https://raw.githubusercontent.com/ome/ngff-spec/$1/schemas/$2 [R=301,L]
"""
From 6b055b2f520adebc72b4bb5ef1148696320dda7e Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Sat, 15 Aug 2026 00:24:19 +0200
Subject: [PATCH 5/6] feat: try direct serve
---
conf.py | 38 +++++++++++++++++++++++++++++---------
1 file changed, 29 insertions(+), 9 deletions(-)
diff --git a/conf.py b/conf.py
index c0a737c3..6843f417 100644
--- a/conf.py
+++ b/conf.py
@@ -103,15 +103,35 @@ def build_served_html():
os.chdir(Path(__file__).parent)
- # Create .htaccess to redirect all schema requests to GitHub
- # ponytail: one rewrite rule handles all versions/files, avoids generating per-file stubs
- os.makedirs("_html_extra", exist_ok=True)
- htaccess_content = """RewriteEngine On
-RewriteRule ^([^/]+)/schemas/(.*)$ https://raw.githubusercontent.com/ome/ngff-spec/$1/schemas/$2 [R=301,L]
-"""
- with open("_html_extra/.htaccess", "w") as f:
- f.write(htaccess_content)
- print(f"✅ Created .htaccess redirect for all schemas → GitHub raw")
+ # Fetch GitHub tags and download schemas
+ try:
+ result = subprocess.check_output([
+ "git", "ls-remote", "--tags", "https://github.com/ome/ngff-spec"
+ ], text=True, timeout=10)
+ tags = [line.split()[1].replace("refs/tags/", "").rstrip("^{}") for line in result.strip().split("\n") if line]
+ for tag in sorted(set(tags)):
+ schema_dir = f"_html_extra/{tag}/schemas"
+ os.makedirs(schema_dir, exist_ok=True)
+ # Download schemas from GitHub raw for this tag
+ gh_url = f"https://github.com/ome/ngff-spec/archive/refs/tags/{tag}.tar.gz"
+ try:
+ import tempfile, tarfile
+ with tempfile.NamedTemporaryFile(delete=False) as tmp:
+ subprocess.check_call(["curl", "-sL", gh_url, "-o", tmp.name])
+ with tarfile.open(tmp.name) as tar:
+ for member in tar.getmembers():
+ if "/schemas/" in member.name and member.name.endswith(".schema"):
+ # Extract just the filename, flatten into schema_dir
+ target = os.path.join(schema_dir, os.path.basename(member.name))
+ tar.extract(member, path=tempfile.gettempdir())
+ src = os.path.join(tempfile.gettempdir(), member.name)
+ shutil.copy2(src, target)
+ os.unlink(tmp.name)
+ print(f"✅ Downloaded schemas for {tag}")
+ except Exception as e:
+ print(f"⚠️ Could not download schemas for {tag}: {e}")
+ except Exception:
+ pass
# Build specifications from local submodules
displayed_spec_versions = [
From acb2ee1e532f2288b93b8b45ca356f72bf209802 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Sat, 15 Aug 2026 00:30:01 +0200
Subject: [PATCH 6/6] feat: dorce display, not download of schemas
---
conf.py | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/conf.py b/conf.py
index 6843f417..10ae3fbd 100644
--- a/conf.py
+++ b/conf.py
@@ -103,6 +103,16 @@ def build_served_html():
os.chdir(Path(__file__).parent)
+ # Create .htaccess to serve schemas inline (not download)
+ os.makedirs("_html_extra", exist_ok=True)
+ htaccess_content = """
+ Header set Content-Disposition "inline"
+
+"""
+ with open("_html_extra/.htaccess", "w") as f:
+ f.write(htaccess_content)
+ print(f"✅ Created .htaccess to serve schemas inline")
+
# Fetch GitHub tags and download schemas
try:
result = subprocess.check_output([