From 0d1164abe0eb53b7d59cf127cfada6d1a1652184 Mon Sep 17 00:00:00 2001 From: Ewan Crawford Date: Wed, 17 Jun 2026 11:58:47 +0100 Subject: [PATCH] Document Docker build The repository README doesn't currently mention Docker, but this is the easiest way to build the OpenCL-Docs specs, as opposed to manually configuring some quite dated ruby dependencies. This PR updates the README to alert to developers that Docker is available help them build the project. It is worth noting that the build instructions for both [Vulkan BUILD.adoc](https://github.com/KhronosGroup/Vulkan-Docs/blob/main/BUILD.adoc#khronos-provided-docker-image) and [SYCL README](https://github.com/KhronosGroup/SYCL-Docs#building-using-the-khronos-docker-image) only document building the project using the docker image. We should consider whether we want a larger rewrite of the OpenCL REAME to only describe building the repo in terms of Docker, but for now the PR makes an incremental improvement. --- README.adoc | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index c19e8c8ee..24689af07 100644 --- a/README.adoc +++ b/README.adoc @@ -73,8 +73,17 @@ We intend to maintain a linear history on the GitHub `main` branch. [[building]] == Building The Specifications and Reference Pages -If you have installed all <>, you -should be able to build both HTML and PDF outputs for all specifications by: +After cloning the repository you should install all of the <>. +The recommended way to do this is by using the Khronos provided Docker image +`khronosgroup/docker-images:asciidoctor-spec` from DockerHub. +The Dockerfile specifying this image can be found at +https://github.com/KhronosGroup/DockerContainers[KhronosGroup/DockerContainers] +if you need to build a modified or layered image. Due to local and CI caching problems when this image +is updated on dockerhub, the OpenCL-Docs CI uses the SHA256 of the latest image update, +rather than the image name. + +Once you have installed all the dependencies you should be able to build both HTML +and PDF outputs for all specifications by: $ make