From 2d22e1ebb28ca982b2f401d7657d9b34e0b1a00b Mon Sep 17 00:00:00 2001
From: Stephan Hageboeck <stephan.hageboeck@cern.ch>
Date: Mon, 18 May 2026 13:42:09 +0200
Subject: [PATCH 1/8] [ci] Move doxygen job to alma10.

- Base the doxygen job on the alma10 container.
- This allows for using a preinstalled doxygen in the container
  (currently 1.13.2), replacing the manual install of 1.10
- Also use preinstalled XRootD and qhelpgenerator
---
 .github/workflows/root-docs-ci.yml | 36 ++++--------------------------
 1 file changed, 4 insertions(+), 32 deletions(-)

diff --git a/.github/workflows/root-docs-ci.yml b/.github/workflows/root-docs-ci.yml
index b41d0eae316d7..2ae4b08d3a719 100644
--- a/.github/workflows/root-docs-ci.yml
+++ b/.github/workflows/root-docs-ci.yml
@@ -33,7 +33,7 @@ jobs:
       - x64
 
     env:
-      PLATFORM: alma9
+      PLATFORM: alma10
       DOC_DIR: master
       DOC_LOCATION: /github/home
       BASE_REF: master
@@ -44,7 +44,7 @@ jobs:
       contents: read
 
     container:
-      image: registry.cern.ch/root-ci/alma9:buildready
+      image: registry.cern.ch/root-ci/alma10:buildready
       options: '--security-opt label=disable --rm'
       env:
         OS_APPLICATION_CREDENTIAL_ID: '7f5b64a265244623a3a933308569bdba'
@@ -74,32 +74,10 @@ jobs:
         echo TAR_NAME=html${BASE_REF}.tar >> $GITHUB_ENV
         echo DOCDIR_NAME=${BASE_REF} >> $GITHUB_ENV
 
-    # TODO: install latest versions in image on root-ci-images
-    - name: Install Doxygen 1.10.0
-      run : |
-        mkdir -p ${{ github.workspace }}/doxygen
-        curl -L https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.linux.bin.tar.gz | tar -xz -C ${{ github.workspace }}/doxygen/ --strip-components=1
-        echo PATH=$PATH:${{ github.workspace }}/doxygen/bin >> $GITHUB_ENV
-#         git clone --branch Release_1_12_0 https://github.com/doxygen/doxygen.git
-#         cd doxygen
-#         mkdir build
-#         cd build
-#         cmake ..
-#         make -j$(nproc)
-#         echo PATH=$PATH:${{ github.workspace }}/doxygen/build/bin >> $GITHUB_ENV
-#         cd ${{ github.workspace }}
-#         doxygen --version
-
-    - name: Install qhelpgenerator-qt5
-      run: |
-        dnf upgrade -y
-        dnf install -y qt5-doctools
-        which qhelpgenerator-qt5
-
     - name: Apply option overrides
       env:
         OVERRIDES: "testing=Off roottest=Off"
-        CONFIGFILE: '.github/workflows/root-ci-config/buildconfig/alma9.txt'
+        CONFIGFILE: '.github/workflows/root-ci-config/buildconfig/alma10.txt'
       shell: bash
       run: |
         set -x
@@ -170,12 +148,6 @@ jobs:
         path: ${{env.DOC_LOCATION}}/${{env.TAR_NAME}}.gz
         if-no-files-found: error
 
-    - name: Install Kerberos utilities
-      run: dnf -y install krb5-workstation
-
-    - name: Install XRootD client
-      run: dnf -y install xrootd-client
-
     - name: Sync documentation to EOS
       env:
         RWEBEOS_KT: ${{ secrets.RWEBEOS_KT }}
@@ -207,4 +179,4 @@ jobs:
         rm -r html
         xrdcp --parallel 64 -rf ./ ${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}
         cd ..
-        xrdcp -rf ${TAR_NAME}.gz ${EOS_ENDPOINT}/${EOS_BASE_PATH}/download
\ No newline at end of file
+        xrdcp -rf ${TAR_NAME}.gz ${EOS_ENDPOINT}/${EOS_BASE_PATH}/download

From 24814a0b17c5e04741b314a4b9214ef87cba7d88 Mon Sep 17 00:00:00 2001
From: Stephan Hageboeck <stephan.hageboeck@cern.ch>
Date: Mon, 18 May 2026 13:52:08 +0200
Subject: [PATCH 2/8] [ci] Remove the override step from the doxygen job.

Overrides can be specified as command-line arguments, which
significantly shortens the job file.
---
 .github/workflows/root-docs-ci.yml | 26 +++++---------------------
 1 file changed, 5 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/root-docs-ci.yml b/.github/workflows/root-docs-ci.yml
index 2ae4b08d3a719..296d4f33d8689 100644
--- a/.github/workflows/root-docs-ci.yml
+++ b/.github/workflows/root-docs-ci.yml
@@ -39,6 +39,7 @@ jobs:
       BASE_REF: master
       WEB_DIR_NAME: master
       TAR_NAME: htmlmaster.tar
+      OVERRIDES: "testing=Off roottest=Off"
 
     permissions:
       contents: read
@@ -74,25 +75,6 @@ jobs:
         echo TAR_NAME=html${BASE_REF}.tar >> $GITHUB_ENV
         echo DOCDIR_NAME=${BASE_REF} >> $GITHUB_ENV
 
-    - name: Apply option overrides
-      env:
-        OVERRIDES: "testing=Off roottest=Off"
-        CONFIGFILE: '.github/workflows/root-ci-config/buildconfig/alma10.txt'
-      shell: bash
-      run: |
-        set -x
-        echo '' >> "$CONFIGFILE"
-        for ENTRY in $OVERRIDES; do
-            KEY=$( echo "$ENTRY" | cut -d '=' -f 1 )
-            # Add entry to file if not exists, otherwise replace
-            if grep -q "$KEY=" "$CONFIGFILE"; then
-                sed -i "s/$KEY=.*\$/$ENTRY/" "$CONFIGFILE"
-            else
-                echo "$ENTRY" >> "$CONFIGFILE"
-            fi
-        done
-        cat "$CONFIGFILE" || true
-
     - name: Build ROOT - Workflow Dispatch
       if:   github.event_name == 'workflow_dispatch'
       env:
@@ -104,7 +86,8 @@ jobs:
                   --base_ref       ${BASE_REF}
                   --head_ref       ${BASE_REF}
                   --binaries       false
-                  --repository     ${{ github.server_url }}/${{ github.repository }}"
+                  --repository     ${{ github.server_url }}/${{ github.repository }}
+                  --overrides      ${OVERRIDES}"
 
     - name: Build ROOT - Schedule
       if:   github.event_name == 'schedule'
@@ -115,7 +98,8 @@ jobs:
                   --base_ref       ${BASE_REF}
                   --head_ref       ${BASE_REF}
                   --binaries       false
-                  --repository     ${{ github.server_url }}/${{ github.repository }}"
+                  --repository     ${{ github.server_url }}/${{ github.repository }}
+                  --overrides      ${OVERRIDES}"
 
     - name: Run Doxygen
       working-directory: ${{ env.DOC_LOCATION }}

From a55a90df875dc8f253331d3882da55ff5249974b Mon Sep 17 00:00:00 2001
From: Stephan Hageboeck <stephan.hageboeck@cern.ch>
Date: Mon, 18 May 2026 14:14:58 +0200
Subject: [PATCH 3/8] [ci] Remove duplicated build step for doxygen job.

There doesn't seem to be a difference between the build configs, so the
duplicated step was removed.
---
 .github/workflows/root-docs-ci.yml | 17 +----------------
 1 file changed, 1 insertion(+), 16 deletions(-)

diff --git a/.github/workflows/root-docs-ci.yml b/.github/workflows/root-docs-ci.yml
index 296d4f33d8689..a029661f78074 100644
--- a/.github/workflows/root-docs-ci.yml
+++ b/.github/workflows/root-docs-ci.yml
@@ -75,22 +75,7 @@ jobs:
         echo TAR_NAME=html${BASE_REF}.tar >> $GITHUB_ENV
         echo DOCDIR_NAME=${BASE_REF} >> $GITHUB_ENV
 
-    - name: Build ROOT - Workflow Dispatch
-      if:   github.event_name == 'workflow_dispatch'
-      env:
-          INCREMENTAL: ${{ inputs.incremental == 'true' }}
-      run: ".github/workflows/root-ci-config/build_root.py
-                  --buildtype      Release
-                  --platform       ${{ env.PLATFORM }}
-                  --incremental    ${{ env.INCREMENTAL }}
-                  --base_ref       ${BASE_REF}
-                  --head_ref       ${BASE_REF}
-                  --binaries       false
-                  --repository     ${{ github.server_url }}/${{ github.repository }}
-                  --overrides      ${OVERRIDES}"
-
-    - name: Build ROOT - Schedule
-      if:   github.event_name == 'schedule'
+    - name: Build ROOT
       run: ".github/workflows/root-ci-config/build_root.py
                   --buildtype      Release
                   --platform       ${{ env.PLATFORM }}

From dd01926c8554b8925d60c2cce58dcc4ca2986b63 Mon Sep 17 00:00:00 2001
From: Stephan Hageboeck <stephan.hageboeck@cern.ch>
Date: Tue, 19 May 2026 09:01:53 +0200
Subject: [PATCH 4/8] [ci][docs] Simplify the tar step.

---
 .github/workflows/root-docs-ci.yml | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/root-docs-ci.yml b/.github/workflows/root-docs-ci.yml
index a029661f78074..0a9e4e9203ed8 100644
--- a/.github/workflows/root-docs-ci.yml
+++ b/.github/workflows/root-docs-ci.yml
@@ -38,7 +38,7 @@ jobs:
       DOC_LOCATION: /github/home
       BASE_REF: master
       WEB_DIR_NAME: master
-      TAR_NAME: htmlmaster.tar
+      TAR_NAME: htmlmaster.tar.gz
       OVERRIDES: "testing=Off roottest=Off"
 
     permissions:
@@ -70,11 +70,6 @@ jobs:
       # code of the `if`.
       run: 'if [ -d /py-venv/ROOT-CI/bin/ ]; then . /py-venv/ROOT-CI/bin/activate && echo PATH=$PATH >> $GITHUB_ENV; fi'
 
-    - name: Set up directory name and tar filenames
-      run: |
-        echo TAR_NAME=html${BASE_REF}.tar >> $GITHUB_ENV
-        echo DOCDIR_NAME=${BASE_REF} >> $GITHUB_ENV
-
     - name: Build ROOT
       run: ".github/workflows/root-ci-config/build_root.py
                   --buildtype      Release
@@ -104,8 +99,7 @@ jobs:
         echo ${DOC_DIR}
         echo ${TAR_NAME}
         ls -l ${DOC_DIR}
-        tar cf ${TAR_NAME} ${DOC_DIR}
-        gzip ${TAR_NAME}
+        tar -caf ${TAR_NAME} ${DOC_DIR}
         ls -l
 
     #Upload to GitHub as an artifact
@@ -113,8 +107,8 @@ jobs:
       if:   ${{ !cancelled() }}
       uses: actions/upload-artifact@v6
       with:
-        name: ${{env.TAR_NAME}}.gz
-        path: ${{env.DOC_LOCATION}}/${{env.TAR_NAME}}.gz
+        name: ${{env.TAR_NAME}}
+        path: ${{env.DOC_LOCATION}}/${{env.TAR_NAME}}
         if-no-files-found: error
 
     - name: Sync documentation to EOS

From b4bfbb67919da1d6ce9d7a343f8a64c4f9843261 Mon Sep 17 00:00:00 2001
From: Stephan Hageboeck <stephan.hageboeck@cern.ch>
Date: Mon, 18 May 2026 14:16:25 +0200
Subject: [PATCH 5/8] [ci][docs] Allow for choosing an eos upload directory.

Add two job inputs for the workflow trigger. These should allow for
choosing a ROOT version to build docs for, and for choosing a directory
where the generated page should be served. Omitting the page means no
upload to eos.
---
 .github/workflows/root-docs-ci.yml | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/root-docs-ci.yml b/.github/workflows/root-docs-ci.yml
index 0a9e4e9203ed8..f443e3e28d922 100644
--- a/.github/workflows/root-docs-ci.yml
+++ b/.github/workflows/root-docs-ci.yml
@@ -17,11 +17,16 @@ on:
         type: boolean
         required: false
         default: false
-      # docu_input: # opportunity: overwrite makeinput.sh with these args
-      #   description: Folders to build documentation for. All folders are built if empty.
-      #   type: string
-      #   default: ""
-      #   required: false
+      input_branch:
+        description: 'Which branch to build documentation for'
+        type: string
+        required: false
+        default: 'master'
+      eos_upload_directory:
+        description: 'Make documentation available at <root-website>/doc/<directory>. Leave empty for skipping the upload to eos.'
+        type: string
+        required: false
+        default: 'master'
 
 jobs:
   build-docs:
@@ -36,8 +41,8 @@ jobs:
       PLATFORM: alma10
       DOC_DIR: master
       DOC_LOCATION: /github/home
-      BASE_REF: master
-      WEB_DIR_NAME: master
+      BASE_REF: ${{ inputs.input_branch == null && 'master' || inputs.input_branch }}
+      WEB_DIR_NAME: ${{ inputs.eos_upload_directory == null && '' || inputs.eos_upload_directory }}
       TAR_NAME: htmlmaster.tar.gz
       OVERRIDES: "testing=Off roottest=Off"
 
@@ -112,6 +117,7 @@ jobs:
         if-no-files-found: error
 
     - name: Sync documentation to EOS
+      if: ${{ env.WEB_DIR_NAME != null && env.WEB_DIR_NAME != '' }}
       env:
         RWEBEOS_KT: ${{ secrets.RWEBEOS_KT }}
         KRB5USER: ${{ secrets.KRB5USER }}

From b6acaf47d7eae56feb1e20227d1b8f6d39a35ffa Mon Sep 17 00:00:00 2001
From: Stephan Hageboeck <stephan.hageboeck@cern.ch>
Date: Mon, 18 May 2026 14:19:02 +0200
Subject: [PATCH 6/8] [ci][docs] Make actionlint and shellcheck happier with
 the workflow.

- Quote many variables to prevent word splitting or unwanted globbing
---
 .github/workflows/root-docs-ci.yml | 32 +++++++++++++++---------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/.github/workflows/root-docs-ci.yml b/.github/workflows/root-docs-ci.yml
index f443e3e28d922..7bc6d883b88a8 100644
--- a/.github/workflows/root-docs-ci.yml
+++ b/.github/workflows/root-docs-ci.yml
@@ -91,9 +91,9 @@ jobs:
       shell: bash
       run: |
         source ROOT-CI/build/bin/thisroot.sh
-        export DOXYGEN_OUTPUT_DIRECTORY=/github/home/${DOC_DIR}
+        export DOXYGEN_OUTPUT_DIRECTORY="/github/home/${DOC_DIR}"
         cd ROOT-CI/src/documentation/doxygen
-        make -j `nproc --all`
+        make -j "$(nproc --all)"
 
     - name: Create documentation archives
       working-directory: ${{ env.DOC_LOCATION }}
@@ -132,20 +132,20 @@ jobs:
       # them by extension. Once that is fixed in XRootD, a single command can be used
       # instead.
       run: |
-        echo ${RWEBEOS_KT} | base64 -d > ${KT_FILE_NAME}
-        kinit -p ${{ secrets.KRB5USER }}@${{ secrets.KRB5REALM }} -kt ${KT_FILE_NAME}
-        cd ${DOC_DIR}/html/
-        xrdcp --parallel 64 -rf ./*.html ${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}
-        rm -rf *.html
-        xrdcp --parallel 64 -rf ./*.svg ${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}
-        rm -rf *.svg
-        xrdcp --parallel 64 -rf ./*.map ${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}
-        rm -rf *.map
-        xrdcp --parallel 64 -rf ./*.md5 ${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}
-        rm -rf *.md5
-        xrdcp --parallel 64 -rf ./ ${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}
+        echo "${RWEBEOS_KT}" | base64 -d > "${KT_FILE_NAME}"
+        kinit -p "${{ secrets.KRB5USER }}@${{ secrets.KRB5REALM }}" -kt "${KT_FILE_NAME}"
+        cd "${DOC_DIR}/html/"
+        xrdcp --parallel 64 -rf ./*.html "${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}"
+        rm -rf ./*.html
+        xrdcp --parallel 64 -rf ./*.svg "${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}"
+        rm -rf ./*.svg
+        xrdcp --parallel 64 -rf ./*.map "${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}"
+        rm -rf ./*.map
+        xrdcp --parallel 64 -rf ./*.md5 "${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}"
+        rm -rf ./*.md5
+        xrdcp --parallel 64 -rf ./ "${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}"
         cd ..
         rm -r html
-        xrdcp --parallel 64 -rf ./ ${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}
+        xrdcp --parallel 64 -rf ./ "${EOS_ENDPOINT}/${EOS_BASE_PATH}/doc/${WEB_DIR_NAME}"
         cd ..
-        xrdcp -rf ${TAR_NAME}.gz ${EOS_ENDPOINT}/${EOS_BASE_PATH}/download
+        xrdcp -rf "${TAR_NAME}.gz" "${EOS_ENDPOINT}/${EOS_BASE_PATH}/download"

From dbc8a6e4ecff01565cb6652e2b4822c2449ace94 Mon Sep 17 00:00:00 2001
From: Stephan Hageboeck <stephan.hageboeck@cern.ch>
Date: Mon, 18 May 2026 14:32:59 +0200
Subject: [PATCH 7/8] [ci][docs] Add a pull request trigger for the doxygen CI
 job.

This job triggers if root-docs-ci.yml or the doxygen folder are touched.
---
 .github/workflows/root-docs-ci.yml | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/root-docs-ci.yml b/.github/workflows/root-docs-ci.yml
index 7bc6d883b88a8..89a1f4eade471 100644
--- a/.github/workflows/root-docs-ci.yml
+++ b/.github/workflows/root-docs-ci.yml
@@ -1,9 +1,13 @@
 name: 'ROOT Docs CI'
 
 on:
+  pull_request:
+    paths:
+      - '.github/workflows/root-docs-ci.yml'
+      - 'documentation/doxygen/**'
+    branches:
+      - 'master'
 
-  # Allows nightly builds to trigger one run for each branch easily, by
-  # providing the relevant branch as "default" value here:
   workflow_call:
     inputs:
       incremental:
@@ -52,6 +56,8 @@ jobs:
     container:
       image: registry.cern.ch/root-ci/alma10:buildready
       options: '--security-opt label=disable --rm'
+      volumes:
+        - alma10_ccache_volume:/github/home/.cache/ccache
       env:
         OS_APPLICATION_CREDENTIAL_ID: '7f5b64a265244623a3a933308569bdba'
         OS_APPLICATION_CREDENTIAL_SECRET: ${{ secrets.OS_APPLICATION_CREDENTIAL_SECRET }}
@@ -79,12 +85,13 @@ jobs:
       run: ".github/workflows/root-ci-config/build_root.py
                   --buildtype      Release
                   --platform       ${{ env.PLATFORM }}
-                  --incremental    ${{ inputs.incremental }}
+                  --incremental    ${{ inputs.incremental == null && 'false' || inputs.incremental }}
                   --base_ref       ${BASE_REF}
                   --head_ref       ${BASE_REF}
-                  --binaries       false
                   --repository     ${{ github.server_url }}/${{ github.repository }}
-                  --overrides      ${OVERRIDES}"
+                  --overrides      ${OVERRIDES}
+                  --upload_artifacts false
+                  --binaries         false"
 
     - name: Run Doxygen
       working-directory: ${{ env.DOC_LOCATION }}

From 02dfba32b3b5d22b82be8fcc6cff5ebf54f5e698 Mon Sep 17 00:00:00 2001
From: Stephan Hageboeck <stephan.hageboeck@cern.ch>
Date: Tue, 19 May 2026 11:57:38 +0200
Subject: [PATCH 8/8] squash! [ci] Remove the override step from the doxygen
 job.

[ci][docs]
---
 .github/workflows/root-docs-ci.yml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/workflows/root-docs-ci.yml b/.github/workflows/root-docs-ci.yml
index 89a1f4eade471..bcd383b609416 100644
--- a/.github/workflows/root-docs-ci.yml
+++ b/.github/workflows/root-docs-ci.yml
@@ -48,7 +48,6 @@ jobs:
       BASE_REF: ${{ inputs.input_branch == null && 'master' || inputs.input_branch }}
       WEB_DIR_NAME: ${{ inputs.eos_upload_directory == null && '' || inputs.eos_upload_directory }}
       TAR_NAME: htmlmaster.tar.gz
-      OVERRIDES: "testing=Off roottest=Off"
 
     permissions:
       contents: read
@@ -89,7 +88,7 @@ jobs:
                   --base_ref       ${BASE_REF}
                   --head_ref       ${BASE_REF}
                   --repository     ${{ github.server_url }}/${{ github.repository }}
-                  --overrides      ${OVERRIDES}
+                  --overrides      testing=Off roottest=Off
                   --upload_artifacts false
                   --binaries         false"