Add OS image location rST directive for use by Red-Install-Tests (#6786)

docs/_ext/prompt_builder.py

@@ -4,25 +4,34 @@ import json
 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 @@ class PromptTranslator(SphinxTranslator):
             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 @@ class PromptTranslator(SphinxTranslator):
     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 @@ class PromptBuilder(TextBuilder):
 
         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

docs/install_guides/ubuntu-2404.rst

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

docs/install_guides/windows.rst

@@ -1,4 +1,22 @@
 .. _windows-install-guide:
+.. os-image-location::
+
+    # The below links are to **Evaluation** ISOs, which can be used for evaluation, **test**, or demonstration purposes.
+    # DO NOT change this to non-evaluation ISOs as those can only be used legally with a valid license.
+    [windows-10]
+    os = 'windows'
+    download_type = 'direct-url'
+    image_format = 'raw'
+    # https://web.archive.org/web/20250701150148/https://www.microsoft.com/en-us/evalcenter/download-windows-10-enterprise
+    url = 'https://software-static.download.prss.microsoft.com/dbazure/988969d5-f34g-4e03-ac9d-1f9786c66750/19045.2006.220908-0225.22h2_release_svc_refresh_CLIENTENTERPRISEEVAL_OEMRET_x64FRE_en-us.iso'
+    checksum = 'sha256:ef7312733a9f5d7d51cfa04ac497671995674ca5e1058d5164d6028f0938d668'
+
+    [windows-11]
+    os = 'windows'
+    download_type = 'direct-url'
+    image_format = 'raw'
+    url = 'https://software-static.download.prss.microsoft.com/dbazure/888969d5-f34g-4e03-ac9d-1f9786c66749/26200.6584.250915-1905.25h2_ge_release_svc_refresh_CLIENTENTERPRISEEVAL_OEMRET_x64FRE_en-us.iso'
+    checksum = 'sha256:a61adeab895ef5a4db436e0a7011c92a2ff17bb0357f58b13bbc4062e535e7b9'
 
 =========================
 Installing Red on Windows
@@ -27,6 +45,7 @@ right-click on it and then click "Run as administrator".
 Then run each of the following commands:
 
 .. prompt:: powershell
+    :modifiers: red-install-guide-elevated
 
     Set-ExecutionPolicy Bypass -Scope Process -Force
     [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
@@ -38,6 +57,7 @@ Then run each of the following commands:
 For Audio support, you should also run the following command before exiting:
 
 .. prompt:: powershell
+    :modifiers: red-install-guide-elevated
 
     choco upgrade temurin25 -y
 

requirements/extra-doc.in

@@ -5,3 +5,4 @@ sphinx-markdown-builder>=0.6.10
 sphinx-prompt
 sphinx_rtd_theme>1
 sphinxcontrib-trio
+tomli

requirements/extra-doc.txt

@@ -58,6 +58,8 @@ sphinxcontrib-trio==1.2.0
     # via -r extra-doc.in
 tabulate==0.9.0
     # via sphinx-markdown-builder
+tomli==2.4.0
+    # via -r extra-doc.in
 urllib3==2.2.3
     # via requests
 zipp==3.20.2