From 9b3debf3022310601ba99a94d621661e9699066d Mon Sep 17 00:00:00 2001 From: EddyCMWF Date: Mon, 22 Jun 2026 16:58:58 +0100 Subject: [PATCH 1/4] common source for ek-packages --- docs/source/conf.py | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 6825ea0e7..c9e5ae5ba 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -10,6 +10,7 @@ import json import os import sys +import urllib.request import yaml @@ -234,11 +235,22 @@ } +_EARTHKIT_PACKAGES_URL = ( + "https://raw.githubusercontent.com/ecmwf/earthkit/refs/heads/develop/docs/earthkit-packages.yml" +) + def _write_earthkit_packages_js(app): - """Read earthkit-packages.yml and write a JS data file into the output _static dir.""" - config_path = os.path.join(os.path.dirname(__file__), "earthkit-packages.yml") - with open(config_path, encoding="utf-8") as fh: - config = yaml.safe_load(fh) + """Fetch earthkit-packages.yml from remote and write a JS data file into the output _static dir. + + Falls back to the local copy if the remote fetch fails. + """ + try: + with urllib.request.urlopen(_EARTHKIT_PACKAGES_URL, timeout=10) as response: + config = yaml.safe_load(response.read()) + except Exception: + config_path = os.path.join(os.path.dirname(__file__), "earthkit-packages.yml") + with open(config_path, encoding="utf-8") as fh: + config = yaml.safe_load(fh) packages = config.get("packages", []) static_dir = os.path.join(app.outdir, "_static") os.makedirs(static_dir, exist_ok=True) From 319079eb7059756f50117494e64225805a0a4453 Mon Sep 17 00:00:00 2001 From: EddyCMWF Date: Mon, 22 Jun 2026 17:01:38 +0100 Subject: [PATCH 2/4] QA for docs --- docs/source/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index c9e5ae5ba..bf403c813 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -239,6 +239,7 @@ "https://raw.githubusercontent.com/ecmwf/earthkit/refs/heads/develop/docs/earthkit-packages.yml" ) + def _write_earthkit_packages_js(app): """Fetch earthkit-packages.yml from remote and write a JS data file into the output _static dir. From 93b0b964b216fce0c3fd1354e6bf7bb260cf22b4 Mon Sep 17 00:00:00 2001 From: EddyCMWF Date: Tue, 23 Jun 2026 11:51:52 +0100 Subject: [PATCH 3/4] source_branch --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index bf403c813..4fa8a0937 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -236,7 +236,7 @@ _EARTHKIT_PACKAGES_URL = ( - "https://raw.githubusercontent.com/ecmwf/earthkit/refs/heads/develop/docs/earthkit-packages.yml" + f"https://raw.githubusercontent.com/ecmwf/earthkit/refs/heads/{source_branch}/docs/earthkit-packages.yml" ) From 6c98f8102306eff3f676b0d3d265c859c0081a2a Mon Sep 17 00:00:00 2001 From: EddyCMWF Date: Tue, 23 Jun 2026 15:57:36 +0100 Subject: [PATCH 4/4] common ek pakages file --- docs/source/conf.py | 42 +++++++++---------------------- docs/source/earthkit_packages.py | 43 ++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 30 deletions(-) create mode 100644 docs/source/earthkit_packages.py diff --git a/docs/source/conf.py b/docs/source/conf.py index 4fa8a0937..a1227b800 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -7,12 +7,8 @@ # -- Import and path setup --------------------------------------------------- import datetime -import json import os import sys -import urllib.request - -import yaml on_rtd = os.environ.get("READTHEDOCS") == "True" @@ -31,6 +27,16 @@ else: source_branch = "main" +# Branch for upstream earthkit repo (used for fetching earthkit-packages.yml) +# Tags will use main +if rtd_version_type in ("tag"): + ek_branch = "main" +# Pull requests and unknmown versions will use develop +# Not sure how you get unknown, but its a valid value of rtd_version_type +elif rtd_version_type in ("external", "unknown"): + ek_branch = "develop" +else: + ek_branch = rtd_version sys.path.insert(0, os.path.abspath("../../src")) sys.path.insert(0, os.path.abspath("./")) @@ -235,33 +241,9 @@ } -_EARTHKIT_PACKAGES_URL = ( - f"https://raw.githubusercontent.com/ecmwf/earthkit/refs/heads/{source_branch}/docs/earthkit-packages.yml" -) - - -def _write_earthkit_packages_js(app): - """Fetch earthkit-packages.yml from remote and write a JS data file into the output _static dir. - - Falls back to the local copy if the remote fetch fails. - """ - try: - with urllib.request.urlopen(_EARTHKIT_PACKAGES_URL, timeout=10) as response: - config = yaml.safe_load(response.read()) - except Exception: - config_path = os.path.join(os.path.dirname(__file__), "earthkit-packages.yml") - with open(config_path, encoding="utf-8") as fh: - config = yaml.safe_load(fh) - packages = config.get("packages", []) - static_dir = os.path.join(app.outdir, "_static") - os.makedirs(static_dir, exist_ok=True) - js_path = os.path.join(static_dir, "earthkit-packages.js") - with open(js_path, "w", encoding="utf-8") as fh: - fh.write(f"window.earthkitPackages = {json.dumps(packages)};\n") - - def setup(app): + from earthkit_packages import _write_earthkit_packages_js from skip_api_rules import _skip_api_items - app.connect("builder-inited", _write_earthkit_packages_js) + app.connect("builder-inited", lambda app: _write_earthkit_packages_js(app, ek_branch)) app.connect("autoapi-skip-member", _skip_api_items) diff --git a/docs/source/earthkit_packages.py b/docs/source/earthkit_packages.py new file mode 100644 index 000000000..b5952b868 --- /dev/null +++ b/docs/source/earthkit_packages.py @@ -0,0 +1,43 @@ +# (C) Copyright 2021 ECMWF. +# +# This software is licensed under the terms of the Apache Licence Version 2.0 +# which can be obtained at http://www.apache.org/licenses/LICENSE-2.0. +# In applying this licence, ECMWF does not waive the privileges and immunities +# granted to it by virtue of its status as an intergovernmental organisation +# nor does it submit to any jurisdiction. +# + +import json +import os +import urllib.request + +import yaml + + +def _write_earthkit_packages_js(app, ek_branch): + """Fetch earthkit-packages.yml from remote and write a JS data file into the output _static dir. + + Falls back to the local copy if the remote fetch fails. + """ + urls = ( + f"https://raw.githubusercontent.com/ecmwf/earthkit/refs/heads/{ek_branch}/docs/earthkit-packages.yml", + "https://raw.githubusercontent.com/ecmwf/earthkit/refs/heads/main/docs/earthkit-packages.yml", + "https://raw.githubusercontent.com/ecmwf/earthkit/refs/heads/develop/docs/earthkit-packages.yml", + ) + + for url in urls: + try: + with urllib.request.urlopen(url, timeout=10) as response: + config = yaml.safe_load(response.read()) + break + except Exception: + continue + else: + raise RuntimeError("Failed to fetch earthkit-packages.yml from remote URLs.") + + packages = config.get("packages", []) + static_dir = os.path.join(app.outdir, "_static") + os.makedirs(static_dir, exist_ok=True) + js_path = os.path.join(static_dir, "earthkit-packages.js") + with open(js_path, "w", encoding="utf-8") as fh: + fh.write(f"window.earthkitPackages = {json.dumps(packages)};\n")