deploy_docs.yml

# *******************************************************************************
# Copyright (c) 2026 Contributors to the Eclipse Foundation
#
# See the NOTICE file(s) distributed with this work for additional
# information regarding copyright ownership.
#
# This program and the accompanying materials are made available under the
# terms of the Apache License Version 2.0 which is available at
# https://www.apache.org/licenses/LICENSE-2.0
#
# SPDX-License-Identifier: Apache-2.0
# *******************************************************************************

# Workflow to build and deploy Sphinx documentation to GitHub Pages with versioning
name: Deploy Documentation to GitHub Pages

on:
  push:
    branches: [main]
    tags: ['v*']
  pull_request:
    branches: [main]
    paths:
      - 'docs/**'
      - '.github/workflows/deploy_docs.yml'
  workflow_dispatch:
  workflow_run:
    workflows: ["Nightly Quality Jobs"]
    types: [completed]

permissions:
  contents: write  # needed for uploading release assets
  pages: write
  id-token: write
  actions: read    # needed to download artifacts from the nightly workflow_run

concurrency:
  group: "pages"
  cancel-in-progress: false

env:
  ANDROID_HOME: ""
  ANDROID_SDK_ROOT: ""
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6.0.2

      - name: Set up Bazel
        uses: castler/setup-bazel@cache-optimized
        with:
          bazelisk-cache: true
          disk-cache: ${{ github.workflow }}
          repository-cache: true
          cache-optimized: true
          cache-save: ${{ github.ref == 'refs/heads/main' }}

      - name: Determine version
        id: version
        run: |
          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
            VERSION="${GITHUB_REF#refs/tags/}"
            echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
            echo "is_tag=true" >> "$GITHUB_OUTPUT"
            echo "should_deploy=true" >> "$GITHUB_OUTPUT"
          elif [[ "${GITHUB_REF}" == refs/heads/main ]]; then
            echo "version=latest" >> "$GITHUB_OUTPUT"
            echo "is_tag=false" >> "$GITHUB_OUTPUT"
            echo "should_deploy=true" >> "$GITHUB_OUTPUT"
          else
            # Feature branch or PR - deploy to preview/<branch-name>
            BRANCH_NAME="${GITHUB_REF#refs/heads/}"
            BRANCH_NAME="${BRANCH_NAME//\//-}"
            echo "version=preview/${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
            echo "is_tag=false" >> "$GITHUB_OUTPUT"
            echo "should_deploy=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Build Sphinx documentation
        run: |
          VERSION="${{ steps.version.outputs.version }}"
          BASE_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
          bazel build //docs/sphinx:sphinx_doc \
            --define=DOCS_VERSION="${VERSION}" \
            --define=DOCS_BASE_URL="${BASE_URL}"

      - name: Prepare documentation output
        run: |
          mkdir -p docs_output
          cp -r bazel-bin/docs/sphinx/sphinx_doc/html/* docs_output/ || \
            cp -r bazel-out/k8-fastbuild/bin/docs/sphinx/sphinx_doc/html/* docs_output/ || true
          # Fix read-only permissions from Bazel output
          chmod -R u+w docs_output/
          # Prevent Jekyll from ignoring _static directories
          touch docs_output/.nojekyll
          # Inject version flyout CSS and JS into all HTML files
          # Use shared path so all versions use the same files
          REPO_NAME="${{ github.event.repository.name }}"
          CSS_TAG="<link rel=\"stylesheet\" type=\"text/css\" href=\"/${REPO_NAME}/_shared/css/version_flyout.css\" />"
          JS_TAG="<script src=\"/${REPO_NAME}/_shared/js/version_flyout.js\"></script>"
          find docs_output -name '*.html' -exec sed -i \
            "s|</head>|${CSS_TAG}\n</head>|" {} +
          find docs_output -name '*.html' -exec sed -i \
            "s|</body>|${JS_TAG}\n</body>|" {} +

      - name: Verify build output
        run: |
          if [ ! -f docs_output/index.html ]; then
            echo "::error::Documentation build failed - no index.html found"
            exit 1
          fi
          echo "Documentation built successfully"
          echo "Files generated:"
          find docs_output -type f | head -20 || true  # head closes the pipe early, causing find to get SIGPIPE. prevents set -e from failing the step

      - name: Upload docs to release
        if: startsWith(github.ref, 'refs/tags/v')
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          VERSION="${{ steps.version.outputs.version }}"
          tar czf "docs-${VERSION}.tar.gz" -C docs_output .
          gh release create "${VERSION}" --draft=false --notes "Release ${VERSION}" 2>/dev/null || true
          gh release upload "${VERSION}" "docs-${VERSION}.tar.gz" --clobber

      - name: Download previously released versions
        if: github.event_name != 'pull_request'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          VERSION="${{ steps.version.outputs.version }}"
          mkdir -p publish
          for tag in $(gh api "repos/${{ github.repository }}/releases" --paginate --jq '.[].tag_name' | grep '^v'); do
            if [ "${tag}" = "${VERSION}" ]; then
              continue
            fi
            if gh release download "${tag}" --pattern "docs-${tag}.tar.gz" --dir /tmp 2>/dev/null; then
              mkdir -p "publish/${tag}"
              tar xzf "/tmp/docs-${tag}.tar.gz" -C "publish/${tag}"
              rm -f "/tmp/docs-${tag}.tar.gz"
              echo "Restored ${tag} from release artifact"
            else
              echo "::warning::No docs artifact found for release ${tag}"
            fi
          done

      - name: Assemble publish tree
        if: github.event_name != 'pull_request'
        run: |
          bazel run //docs/sphinx/utils:assemble_publish_tree -- \
            --version     "${{ steps.version.outputs.version }}" \
            --is-tag      "${{ steps.version.outputs.is_tag }}" \
            --docs-output docs_output \
            --publish-dir publish \
            --repo-url    "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}" \
            --root-index  docs/sphinx/_gh_pages/index.html

      - name: Bundle quality reports into latest/
        if: github.event_name != 'pull_request'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          bash quality/scripts/bundle_quality_reports.sh \
            "${{ github.event_name }}" \
            "${{ github.event.workflow_run.id }}" \
            "${{ github.repository }}"

      - name: Upload Pages artifact
        if: github.event_name != 'pull_request'
        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
        with:
          path: publish

      - name: Print preview URL
        if: github.event_name != 'pull_request'
        run: |
          REPO_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
          echo "::notice::Documentation deployed to: ${REPO_URL}/${{ steps.version.outputs.version }}/"

  deploy-pages:
    needs: build-docs
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5