Add OS image location rST directive for use by Red-Install-Tests

docs/_ext/prompt_builder.py

@@ -4,25 +4,34 @@
 import os
 from typing import Any, Dict, List, Set
 
+import tomli
 from docutils import nodes
 from docutils.io import StringOutput
 from docutils.nodes import Element
-
 from sphinx.application import Sphinx
 from sphinx.builders.text import TextBuilder
 from sphinx.writers.text import TextWriter
 from sphinx.util import logging
-from sphinx.util.docutils import SphinxTranslator
+from sphinx.util.docutils import SphinxDirective, SphinxTranslator
 
 logger = logging.getLogger(__name__)
 
 
+class OSImageLocation(SphinxDirective):
+    has_content = True
+
+    def run(self) -> List[nodes.Node]:
+        data = tomli.loads("\n".join(self.content))
+        return [nodes.raw(json.dumps(data), format="prompt-builder")]
+
+
 class PromptTranslator(SphinxTranslator):
     builder: PromptBuilder
 
     def __init__(self, document: nodes.document, builder: PromptBuilder) -> None:
         super().__init__(document, builder)
         self.body = ""
+        self.os_image_locations: Dict[str, Any] = {}
         self.prompts: List[Dict[str, str]] = []
 
     def visit_document(self, node: Element) -> None:
@@ -33,7 +42,10 @@ def depart_document(self, node: Element) -> None:
             self.body = ""
             return
         if self.builder.out_suffix.endswith(".json"):
-            self.body = json.dumps(self.prompts, indent=4)
+            data: Dict[str, Any] = {"prompts": self.prompts}
+            if self.os_image_locations:
+                data["os_image_locations"] = self.os_image_locations
+            self.body = json.dumps(data, indent=4)
         else:
             self.body = "\n".join(prompt["content"] for prompt in self.prompts)
 
@@ -43,6 +55,11 @@ def unknown_visit(self, node: Element) -> None:
     def unknown_departure(self, node: Element) -> None:
         pass
 
+    def visit_raw(self, node: Element) -> None:
+        if "prompt-builder" not in node.get("format", "").split():
+            raise nodes.SkipNode
+        self.os_image_locations.update(json.loads(node.rawsource))
+
     def visit_prompt(self, node: Element) -> None:
         self.prompts.append(
             {
@@ -81,6 +98,12 @@ def init(self) -> None:
 
         def run(self) -> List[prompt]:
             self.assert_has_content()
+            arg_count = len(self.arguments)
+            for idx, option_name in enumerate(("language", "prompts", "modifiers")):
+                if arg_count > idx:
+                    if self.options.get(option_name):
+                        break
+                    self.options[option_name] = self.arguments[idx]
             rawsource = "\n".join(self.content)
             language = self.options.get("language") or "text"
             prompts = [
@@ -146,6 +169,7 @@ class TextPromptBuilder(PromptBuilder):
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_builder(JsonPromptBuilder)
     app.add_builder(TextPromptBuilder)
+    app.add_directive("os-image-location", OSImageLocation)
 
     return {
         "version": "1.0",

docs/install_guides/alma-linux-8.rst

@@ -1,4 +1,18 @@
 .. _install-alma-linux-8:
+.. os-image-location::
+
+    [alma-linux-8]
+    download_type = 'checksum-file'
+    url = 'https://repo.almalinux.org/almalinux/8/cloud/x86_64/images/CHECKSUM'
+    filename_pattern = 'AlmaLinux-8-GenericCloud-latest\.x86_64\.qcow2'
+    expected_java_version = 21
+
+    [alma-linux-8-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    url = 'https://repo.almalinux.org/almalinux/8/cloud/aarch64/images/CHECKSUM'
+    filename_pattern = 'AlmaLinux-8-GenericCloud-latest\.aarch64\.qcow2'
+    expected_java_version = 21
 
 ====================================
 Installing Red on Alma Linux 8.6-8.x

docs/install_guides/alma-linux-9.rst

@@ -1,4 +1,16 @@
 .. _install-alma-linux-9:
+.. os-image-location::
+
+    [alma-linux-9]
+    download_type = 'checksum-file'
+    url = 'https://repo.almalinux.org/almalinux/9/cloud/x86_64/images/CHECKSUM'
+    filename_pattern = 'AlmaLinux-9-GenericCloud-latest\.x86_64\.qcow2'
+
+    [alma-linux-9-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    url = 'https://repo.almalinux.org/almalinux/9/cloud/aarch64/images/CHECKSUM'
+    filename_pattern = 'AlmaLinux-9-GenericCloud-latest\.aarch64\.qcow2'
 
 ==============================
 Installing Red on Alma Linux 9

docs/install_guides/amazon-linux-2023.rst

@@ -1,4 +1,16 @@
 .. _install-amazon-linux-2023:
+.. os-image-location::
+
+    [amazon-linux-2023]
+    download_type = 'checksum-file'
+    url = 'https://cdn.amazonlinux.com/al2023/os-images/latest/kvm/SHA256SUMS'
+    filename_pattern = '.*\.qcow2'
+
+    [amazon-linux-2023-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    url = 'https://cdn.amazonlinux.com/al2023/os-images/latest/kvm-arm64/SHA256SUMS'
+    filename_pattern = '.*\.qcow2'
 
 ===================================
 Installing Red on Amazon Linux 2023

docs/install_guides/arch.rst

@@ -1,4 +1,10 @@
 .. _install-arch:
+.. os-image-location::
+
+    [arch-linux]
+    download_type = 'checksum-file'
+    url = 'https://fastly.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-cloudimg.qcow2.SHA256'
+    filename_pattern = '.*\.qcow2'
 
 ============================
 Installing Red on Arch Linux

docs/install_guides/centos-stream-9.rst

@@ -1,4 +1,19 @@
 .. _install-centos-stream-9:
+.. os-image-location::
+
+    [centos-stream-9]
+    download_type = 'checksum-file'
+    boot_mode = 'bios'
+    url = 'https://cloud.centos.org/centos/9-stream/x86_64/images/CentOS-Stream-GenericCloud-9-latest.x86_64.qcow2.SHA256SUM'
+    checksum_style = 'bsd'
+    filename_pattern = '.*\.qcow2'
+
+    [centos-stream-9-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    url = 'https://cloud.centos.org/centos/9-stream/aarch64/images/CentOS-Stream-GenericCloud-9-latest.aarch64.qcow2.SHA256SUM'
+    checksum_style = 'bsd'
+    filename_pattern = '.*\.qcow2'
 
 =================================
 Installing Red on CentOS Stream 9

docs/install_guides/debian-12.rst

@@ -1,4 +1,20 @@
 .. _install-debian-12:
+.. os-image-location::
+
+    [debian-12]
+    download_type = 'checksum-file'
+    url = 'https://cloud.debian.org/images/cloud/bookworm/latest/SHA512SUMS'
+    checksum_type = 'sha512'
+    filename_pattern = 'debian-12-generic-amd64\.qcow2'
+    expected_java_version = 17
+
+    [debian-12-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    url = 'https://cloud.debian.org/images/cloud/bookworm/latest/SHA512SUMS'
+    checksum_type = 'sha512'
+    filename_pattern = 'debian-12-genericcloud-arm64\.qcow2'
+    expected_java_version = 17
 
 ====================================
 Installing Red on Debian 12 Bookworm

docs/install_guides/fedora.rst

@@ -1,4 +1,31 @@
 .. _install-fedora:
+.. os-image-location::
+
+    [fedora-43]
+    download_type = 'checksum-file'
+    url = 'https://download.fedoraproject.org/pub/fedora/linux/releases/43/Cloud/x86_64/images/Fedora-Cloud-43-1.6-x86_64-CHECKSUM'
+    checksum_style = 'bsd'
+    filename_pattern = 'Fedora-Cloud-Base-Generic-.*\.qcow2'
+
+    [fedora-43-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    url = 'https://download.fedoraproject.org/pub/fedora/linux/releases/43/Cloud/aarch64/images/Fedora-Cloud-43-1.6-aarch64-CHECKSUM'
+    checksum_style = 'bsd'
+    filename_pattern = 'Fedora-Cloud-Base-Generic-.*\.qcow2'
+
+    [fedora-44]
+    download_type = 'checksum-file'
+    url = 'https://download.fedoraproject.org/pub/fedora/linux/releases/44/Cloud/x86_64/images/Fedora-Cloud-44-1.7-x86_64-CHECKSUM'
+    checksum_style = 'bsd'
+    filename_pattern = 'Fedora-Cloud-Base-Generic-.*\.qcow2'
+
+    [fedora-44-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    url = 'https://download.fedoraproject.org/pub/fedora/linux/releases/44/Cloud/aarch64/images/Fedora-Cloud-44-1.7-aarch64-CHECKSUM'
+    checksum_style = 'bsd'
+    filename_pattern = 'Fedora-Cloud-Base-Generic-.*\.qcow2'
 
 ==============================
 Installing Red on Fedora Linux

docs/install_guides/mac.rst

@@ -1,4 +1,20 @@
 .. _install-mac:
+.. os-image-location::
+
+    [macos-14]
+    os = 'darwin'
+    download_type = 'tart-image'
+    image = 'ghcr.io/cirruslabs/macos-sonoma-vanilla:latest'
+
+    [macos-15]
+    os = 'darwin'
+    download_type = 'tart-image'
+    image = 'ghcr.io/cirruslabs/macos-sequioa-vanilla:latest'
+
+    [macos-26]
+    os = 'darwin'
+    download_type = 'tart-image'
+    image = 'ghcr.io/cirruslabs/macos-tahoe-vanilla:latest'
 
 =======================
 Installing Red on macOS

docs/install_guides/opensuse-leap-15.rst

@@ -1,4 +1,18 @@
 .. _install-opensuse-leap-15:
+.. os-image-location::
+
+    [opensuse-leap-156]
+    download_type = 'checksum-file'
+    url = 'https://download.opensuse.org/distribution/leap/15.6/appliances/openSUSE-Leap-15.6-Minimal-VM.x86_64-Cloud.qcow2.sha256'
+    filename_pattern = '.*\.qcow2'
+    expected_java_version = 21
+
+    [opensuse-leap-156-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    url = 'https://download.opensuse.org/distribution/leap/15.6/appliances/openSUSE-Leap-15.6-Minimal-VM.aarch64-Cloud.qcow2.sha256'
+    filename_pattern = '.*\.qcow2'
+    expected_java_version = 21
 
 =====================================
 Installing Red on openSUSE Leap 15.6+

docs/install_guides/opensuse-tumbleweed.rst

@@ -1,4 +1,16 @@
 .. _install-opensuse-tumbleweed:
+.. os-image-location::
+
+    [opensuse-tumbleweed]
+    download_type = 'checksum-file'
+    url = 'https://download.opensuse.org/tumbleweed/appliances/openSUSE-Tumbleweed-Minimal-VM.x86_64-Cloud.qcow2.sha256'
+    filename_pattern = '.*\.qcow2'
+
+    [opensuse-tumbleweed-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    url = 'https://download.opensuse.org/ports/aarch64/tumbleweed/appliances/openSUSE-Tumbleweed-Minimal-VM.aarch64-Cloud.qcow2.sha256'
+    filename_pattern = '.*\.qcow2'
 
 =====================================
 Installing Red on openSUSE Tumbleweed

docs/install_guides/oracle-linux-8.rst

@@ -1,4 +1,20 @@
 .. _install-oracle-linux-8:
+.. os-image-location::
+
+    [oracle-linux-8]
+    download_type = 'html'
+    url = 'https://yum.oracle.com/oracle-linux-templates.html'
+    url_xpath = ".//*[@id='ol8']//a[@class='kvm-image']/@href"
+    checksum_xpath = ".//*[@id='ol8']//*[@class='kvm-sha256']/text()"
+    expected_java_version = 21
+
+    [oracle-linux-8-arm]
+    download_type = 'html'
+    arch = 'aarch64'
+    url = 'https://yum.oracle.com/oracle-linux-templates.html'
+    url_xpath = ".//*[@id='ol8_aarch64']//a[@class='kvm-image']/@href"
+    checksum_xpath = ".//*[@id='ol8_aarch64']//*[@class='kvm-sha256']/text()"
+    expected_java_version = 21
 
 ======================================
 Installing Red on Oracle Linux 8.6-8.x

docs/install_guides/oracle-linux-9.rst

@@ -1,4 +1,18 @@
 .. _install-oracle-linux-9:
+.. os-image-location::
+
+    [oracle-linux-9]
+    download_type = 'html'
+    url = 'https://yum.oracle.com/oracle-linux-templates.html'
+    url_xpath = ".//*[@id='ol9']//a[@class='kvm-image']/@href"
+    checksum_xpath = ".//*[@id='ol9']//*[@class='kvm-sha256']/text()"
+
+    [oracle-linux-9-arm]
+    download_type = 'html'
+    arch = 'aarch64'
+    url = 'https://yum.oracle.com/oracle-linux-templates.html'
+    url_xpath = ".//*[@id='ol9_aarch64']//a[@class='kvm-image']/@href"
+    checksum_xpath = ".//*[@id='ol9_aarch64']//*[@class='kvm-sha256']/text()"
 
 ================================
 Installing Red on Oracle Linux 9

docs/install_guides/raspberry-pi-os-12.rst

@@ -1,4 +1,8 @@
 .. _install-raspberry-pi-os-12:
+.. os-image-location::
+
+    # cloud-init (which is required for install testing) is not available in Raspberry Pi OS 12
+    # https://www.raspberrypi.com/news/cloud-init-on-raspberry-pi-os/
 
 ======================================================
 Installing Red on Raspberry Pi OS (Legacy) 12 Bookworm

docs/install_guides/rocky-linux-8.rst

@@ -1,4 +1,22 @@
 .. _install-rocky-linux-8:
+.. os-image-location::
+
+    [rocky-linux-8]
+    download_type = 'checksum-file'
+    # one of the mirrors for https://download.rockylinux.org/pub/rocky/8/images/x86_64/CHECKSUM
+    url = 'https://ftp.nluug.nl/pub/os/Linux/distr/rocky/8/images/x86_64/CHECKSUM'
+    checksum_style = 'bsd'
+    filename_pattern = 'Rocky-8-GenericCloud\.latest\.x86_64\.qcow2'
+    expected_java_version = 21
+
+    [rocky-linux-8-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    # one of the mirrors for https://download.rockylinux.org/pub/rocky/8/images/aarch64/CHECKSUM
+    url = 'https://ftp.nluug.nl/pub/os/Linux/distr/rocky/8/images/aarch64/CHECKSUM'
+    checksum_style = 'bsd'
+    filename_pattern = 'Rocky-8-GenericCloud\.latest\.aarch64\.qcow2'
+    expected_java_version = 21
 
 =====================================
 Installing Red on Rocky Linux 8.6-8.x

docs/install_guides/rocky-linux-9.rst

@@ -1,4 +1,20 @@
 .. _install-rocky-linux-9:
+.. os-image-location::
+
+    [rocky-linux-9]
+    download_type = 'checksum-file'
+    # one of the mirrors for https://download.rockylinux.org/pub/rocky/9/images/x86_64/CHECKSUM
+    url = 'https://ftp.nluug.nl/pub/os/Linux/distr/rocky/9/images/x86_64/CHECKSUM'
+    checksum_style = 'bsd'
+    filename_pattern = 'Rocky-9-GenericCloud\.latest\.x86_64\.qcow2'
+
+    [rocky-linux-9-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    # one of the mirrors for https://download.rockylinux.org/pub/rocky/9/images/aarch64/CHECKSUM
+    url = 'https://ftp.nluug.nl/pub/os/Linux/distr/rocky/9/images/aarch64/CHECKSUM'
+    checksum_style = 'bsd'
+    filename_pattern = 'Rocky-9-GenericCloud\.latest\.aarch64\.qcow2'
 
 ===============================
 Installing Red on Rocky Linux 9

docs/install_guides/ubuntu-2204.rst

@@ -1,4 +1,24 @@
 .. _install-ubuntu-2204:
+.. os-image-location::
+
+    [ubuntu-2204]
+    download_type = 'checksum-file'
+    url = 'https://cloud-images.ubuntu.com/jammy/current/SHA256SUMS'
+    filename_pattern = 'jammy-server-cloudimg-amd64\.img'
+
+    [ubuntu-2204-arm]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    url = 'https://cloud-images.ubuntu.com/jammy/current/SHA256SUMS'
+    filename_pattern = 'jammy-server-cloudimg-arm64\.img'
+
+    [ubuntu-2204-arm-raspi]
+    download_type = 'checksum-file'
+    arch = 'aarch64'
+    machine_type = 'raspi3b'
+    image_format = 'raw+xz'
+    url = 'https://cdimage.ubuntu.com/releases/jammy/release/SHA256SUMS'
+    filename_pattern = 'ubuntu-22\.04\.\d+-preinstalled-server-arm64\+raspi\.img\.xz'
 
 ==================================
 Installing Red on Ubuntu 22.04 LTS