ci(docs): add caching and parallel build scripts for doc generation

Add Go module and Hugo resource caching to both hugo-build composite
actions. Optimize Dockerfile with BuildKit cache mounts and better
layer ordering. Add new scripts for parallel versioned doc generation
(discover-versions, generate-single-version, assemble-versions) — not
yet referenced by any workflow.

jira: trivial
risk: nonprod

Author: hkad98

.github/actions/hugo-build-action/action.yaml

@@ -12,6 +12,13 @@ runs:
       uses: actions/setup-go@v5
       with:
         go-version: '>=1.20.1'
+        cache: false
+    - name: "Cache Go modules"
+      uses: actions/cache@v4
+      with:
+        path: ~/go/pkg/mod
+        key: go-mod-${{ hashFiles('docs/go.sum') }}
+        restore-keys: go-mod-
     - name: "Setup Node"
       uses: actions/setup-node@v4
       with:
@@ -28,6 +35,12 @@ runs:
       working-directory: ./docs
       run: |
         npm ci
+    - name: "Cache Hugo resources"
+      uses: actions/cache@v4
+      with:
+        path: docs/resources/_gen
+        key: hugo-resources-${{ hashFiles('docs/go.sum', 'docs/config/**') }}
+        restore-keys: hugo-resources-
     - name: "Build documentation"
       working-directory: ./docs
       env:

.github/actions/hugo-build-versioned-action/action.yaml

@@ -35,6 +35,13 @@ runs:
     - uses: actions/setup-go@v5
       with:
         go-version: '>=1.20.1'
+        cache: false
+    - name: "Cache Go modules"
+      uses: actions/cache@v4
+      with:
+        path: ~/go/pkg/mod
+        key: go-mod-${{ hashFiles('docs/go.sum') }}
+        restore-keys: go-mod-
     - name: "Setup Node"
       uses: actions/setup-node@v4
       with:
@@ -59,6 +66,12 @@ runs:
         wget https://raw.githubusercontent.com/gooddata/gooddata-python-sdk/master/scripts/generate.sh
         chmod +x ./generate.sh
         ./generate.sh ${{ inputs.fetch-from }} master
+    - name: "Cache Hugo resources"
+      uses: actions/cache@v4
+      with:
+        path: docs/resources/_gen
+        key: hugo-resources-${{ hashFiles('docs/go.sum', 'docs/config/**') }}
+        restore-keys: hugo-resources-
     - name: "Build documentation"
       working-directory: ./docs
       env:

docs/Dockerfile

@@ -1,15 +1,21 @@
+# syntax=docker/dockerfile:1
 FROM python:3.14-slim AS builder
 
 RUN apt-get update && apt-get install -y git make curl
 
+# Install Python deps first (changes rarely) for better layer caching.
+# Copy only dependency manifests and package source before installing.
 COPY scripts/script-requirements.txt /scripts/script-requirements.txt
-COPY docs docs
-COPY scripts/docs/ /docs
 COPY gooddata-api-client /gooddata-api-client
 COPY packages/gooddata-sdk /gooddata-sdk
 COPY packages/gooddata-pandas /gooddata-pandas
 
-RUN pip install --no-cache-dir -r /scripts/script-requirements.txt
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install -r /scripts/script-requirements.txt
+
+# Copy source (docs content changes most frequently, scripts less so)
+COPY docs docs
+COPY scripts/docs/ /docs
 
 WORKDIR /docs
 
@@ -21,16 +27,20 @@ RUN python json_builder.py && \
 
 FROM node:20.18.0-bookworm-slim
 
-COPY --from=builder /docs /docs
-
 RUN apt-get update && \
     apt-get install -y git make golang-go curl && \
     npm install -g hugo-extended@0.117.0 && \
     apt-get clean && \
     rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
+COPY --from=builder /docs /docs
+
 WORKDIR /docs
-RUN npm install && \
+
+# Use BuildKit cache mounts so npm/Go package downloads survive layer rebuilds
+RUN --mount=type=cache,target=/root/.npm \
+    --mount=type=cache,target=/root/go/pkg/mod \
+    npm install && \
     hugo mod get
 
 # accessible on http://localhost:1313/latest/

scripts/assemble-versions.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# (C) 2026 GoodData Corporation
+# Assembles version artifacts into the final versioned_docs structure.
+# Run from the docs/ directory after downloading version artifacts.
+#
+# Expects:
+#   - versioned_docs-raw/ directory with version-* subdirectories (from artifact download)
+#   - content/en/ directory with master branch content (from current checkout)
+set -e
+
+content_dir=versioned_docs
+
+# Start with clean versioned_docs
+rm -rf "$content_dir"
+mkdir -p "$content_dir"
+
+# 1. Copy master/current branch content (provides versions page and root structure)
+echo "Copying master content from content/en/"
+cp -r content/en/. "$content_dir/"
+
+# 2. Move version artifacts from download directory into versioned_docs
+if [ -d "versioned_docs-raw" ]; then
+    for dir in versioned_docs-raw/version-*/; do
+        [ -d "$dir" ] || continue
+        section=$(basename "$dir" | sed 's/^version-//')
+        echo "Installing version artifact: $section"
+        # Remove any existing content for this section (from master copy)
+        rm -rf "${content_dir:?}/$section"
+        mv "$dir" "$content_dir/$section"
+    done
+    rm -rf versioned_docs-raw
+fi
+
+# 3. Remove master's "latest" directory — it will be replaced by the highest numbered version
+echo "Removing master's latest directory"
+rm -rf "${content_dir:?}/latest"
+
+# 4. Find the highest numbered version and promote it to "latest"
+highest_version=$(ls -1 "./$content_dir/" | grep -E '^[0-9]+$' | sort -V | tail -n 1)
+
+if [ -n "$highest_version" ]; then
+    echo "Promoting version $highest_version to /latest"
+    mv -f "./$content_dir/$highest_version" "./$content_dir/latest"
+
+    # Update version references in links.json
+    if [ -f "./$content_dir/latest/links.json" ]; then
+        sed "s|${highest_version}|latest|g" "./$content_dir/latest/links.json" > temp_links.json
+        mv temp_links.json "./$content_dir/latest/links.json"
+    fi
+else
+    echo "WARNING: No numbered version directory found to promote to latest"
+fi
+
+echo "Assembly complete. Contents of $content_dir/:"
+ls -la "$content_dir/"

scripts/discover-versions.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# (C) 2026 GoodData Corporation
+# Discovers release versions for parallel doc generation.
+# Outputs a JSON array suitable for GitHub Actions matrix strategy.
+# Usage: discover-versions.sh [remote_name] [num_versions]
+set -e
+
+remote_name=${1:-origin}
+num_versions=${2:-4}
+
+git fetch "$remote_name" 2>/dev/null
+
+# Build a map of section -> branch, keeping only the latest minor per section.
+# Associative arrays preserve last-write-wins semantics, matching the original
+# generate.sh behavior where later branches overwrite earlier ones.
+declare -A section_map
+declare -a section_order
+
+while IFS= read -r vers; do
+    section="${vers%.*}"
+    if [ -z "${section_map[$section]+x}" ]; then
+        section_order+=("$section")
+    fi
+    # Later (higher minor) versions overwrite earlier ones for the same major
+    section_map["$section"]="rel/$vers"
+done < <(git branch -rl "$remote_name/rel/*" | sed 's|.*/rel/||' | grep -E '^[0-9]+\.[0-9]+$' | sort -t. -k1,1n -k2,2n | tail -n"$num_versions")
+
+# Add dev branch if it exists
+if git branch -rl "$remote_name/rel/dev" | grep -q "rel/dev"; then
+    if [ -z "${section_map[dev]+x}" ]; then
+        section_order+=("dev")
+    fi
+    section_map["dev"]="rel/dev"
+fi
+
+# Output as JSON array
+echo -n "["
+first=true
+for section in "${section_order[@]}"; do
+    branch="${section_map[$section]}"
+    if [ "$first" = true ]; then
+        first=false
+    else
+        echo -n ","
+    fi
+    echo -n "{\"branch\":\"$branch\",\"section\":\"$section\"}"
+done
+echo "]"

scripts/generate-single-version.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# (C) 2026 GoodData Corporation
+# Generates documentation for a single version branch.
+# This is the per-version logic extracted from generate.sh for parallel execution.
+#
+# Usage: generate-single-version.sh <full-branch-ref> <section>
+# Example: generate-single-version.sh origin/rel/1.3 1
+#
+# Prerequisites:
+#   - Repository checked out with the target branch fetched
+#   - Python environment with script-requirements.txt installed from the TARGET branch
+set -e
+
+branch=$1
+section=$2
+
+if [ -z "$branch" ] || [ -z "$section" ]; then
+    echo "Usage: generate-single-version.sh <full-branch-ref> <section>"
+    echo "Example: generate-single-version.sh origin/rel/1.3 1"
+    exit 1
+fi
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT/docs"
+
+content_dir=versioned_docs
+
+mkdir -p "$content_dir/$section"
+
+# Determine source content path on the branch
+if git ls-tree -d "$branch" -- "content/en/docs" 2>/dev/null | grep -q "content/en/docs"; then
+    src_section=docs
+else
+    src_section=latest
+fi
+
+# Extract documentation content from the branch
+echo "Extracting docs from $branch for section $section (src=$src_section)"
+# strip-components=3 removes content/en/{src_section} prefix
+git archive "$branch" "content/en/$src_section" | tar xf - -C "$content_dir/$section" \
+    --strip-components=3 "content/en/$src_section"
+
+# Generate API reference if json_builder.py exists on the branch
+API_GEN_FILE="$branch:scripts/docs/json_builder.py"
+if git cat-file -e "$API_GEN_FILE" 2>/dev/null; then
+    echo "Generating API ref for section $section..."
+
+    # Get api_spec.toml from the branch
+    if git ls-tree --name-only "$branch" | grep -q "^api_spec.toml$"; then
+        git checkout "$branch" -- api_spec.toml
+    else
+        echo "No api_spec.toml on $branch, removing local copy"
+        rm -f api_spec.toml
+    fi
+
+    # Generate API introspection data from this version's SDK
+    python3 ../scripts/docs/json_builder.py
+    mv -f data.json "$content_dir/$section/"
+
+    # Generate API reference markdown files
+    python3 ../scripts/docs/python_ref_builder.py api_spec.toml \
+        "./$content_dir/$section/data.json" "$section" "$content_dir"
+else
+    echo "No json_builder.py on $branch, skipping API ref generation"
+fi
+
+echo "Done: section $section from $branch"