docs.yml

name: Publish documentation

run-name: "Publish documentation ${{ github.event.client_payload.tag_name || github.event.release.tag_name || '' }}"

on:
  release:
    types: [ published ]
  repository_dispatch:
    types: [ release-published ]

  workflow_dispatch:

  pull_request:
    types: [ closed ]
    branches: [ main, 1.6.X ]

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write
  issues: read
  pull-requests: read

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Check if a merged PR is linked to a documentation issue
  check-docs-label:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    outputs:
      should_build: ${{ steps.check.outputs.should_build }}
    steps:
      - name: Check for documentation label
        id: check
        uses: actions/github-script@v8
        with:
          script: |
            const merged = context.payload.pull_request.merged;
            if (!merged) {
              core.setOutput('should_build', 'false');
              core.info('PR was closed without merging. Skipping.');
              return;
            }

            const branch = context.payload.pull_request.head.ref;
            core.info(`PR branch: ${branch}`);

            const match = branch.match(/^cr-(\d+)$/);
            if (!match) {
              core.setOutput('should_build', 'false');
              core.info('Branch does not match cr-{number} pattern. Skipping.');
              return;
            }

            const issueNumber = parseInt(match[1], 10);
            core.info(`Extracted issue number: ${issueNumber}`);

            try {
              const issue = await github.rest.issues.get({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: issueNumber,
              });

              const issueLabels = issue.data.labels.map(l => l.name);
              core.info(`Issue #${issueNumber} labels: ${issueLabels.join(', ') || '(none)'}`);

              if (issueLabels.includes('documentation')) {
                core.setOutput('should_build', 'true');
                core.info(`Issue #${issueNumber} has "documentation" label. Will build docs.`);
              } else {
                core.setOutput('should_build', 'false');
                core.info(`Issue #${issueNumber} does not have "documentation" label. Skipping.`);
              }
            } catch (error) {
              core.warning(`Could not fetch issue #${issueNumber}: ${error.message}`);
              core.setOutput('should_build', 'false');
            }

  # Build job
  build:
    needs: [ check-docs-label ]
    if: |
      always() && !cancelled() &&
      (
        github.event_name == 'release' ||
        github.event_name == 'repository_dispatch' ||
        github.event_name == 'workflow_dispatch' ||
        needs.check-docs-label.outputs.should_build == 'true'
      )
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.client_payload.tag_name || github.ref }}
          fetch-depth: 0  # Fetch all history for all tags and branches
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Install poetry
        run: pipx install poetry
      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.12'
          cache: poetry
      - name: Cache ANTLR4 runtime prebuilt
        uses: actions/cache@v4
        id: antlr4-cache
        with:
          path: build/antlr4-prefix
          key: antlr4-runtime-${{ runner.os }}-py3.12-${{ hashFiles('scripts/setup_antlr4_runtime.sh', 'CMakeLists.txt') }}
      - name: Cache C++ parser wheel
        uses: actions/cache@v4
        id: cpp-cache
        with:
          path: .cpp-wheel
          key: cpp-parser-${{ runner.os }}-py3.12-${{ hashFiles('src/vtlengine/AST/Grammar/_cpp_parser/**', 'CMakeLists.txt', 'pyproject.toml') }}
      - name: Download ANTLR4 C++ runtime source
        if: steps.cpp-cache.outputs.cache-hit != 'true' && steps.antlr4-cache.outputs.cache-hit != 'true'
        shell: bash
        run: bash scripts/setup_antlr4_runtime.sh
      - name: Build ANTLR4 runtime
        if: steps.cpp-cache.outputs.cache-hit != 'true' && steps.antlr4-cache.outputs.cache-hit != 'true'
        shell: bash
        run: |
          cmake -S . -B build/antlr4-build \
            -G Ninja \
            -DCMAKE_BUILD_TYPE=Release \
            -DVTLENGINE_BUILD_ANTLR4_PREBUILT=ON
          cmake --build build/antlr4-build --target antlr4_runtime --config Release
          cmake --install build/antlr4-build --prefix "$PWD/build/antlr4-prefix" --config Release
      - name: Build C++ parser wheel
        if: steps.cpp-cache.outputs.cache-hit != 'true'
        shell: bash
        run: |
          pip wheel . -w .cpp-wheel --no-deps -v \
            -C cmake.define.VTLENGINE_USE_PREBUILT_ANTLR4=ON \
            -C "cmake.define.VTLENGINE_ANTLR4_PREFIX=$PWD/build/antlr4-prefix"
      - name: Install dependencies
        shell: bash
        run: |
          poetry install --no-root
          poetry run pip install .cpp-wheel/*.whl
      - name: Configure documentation versions
        run: |
          poetry run python docs/scripts/configure_doc_versions.py
      - name: Build multi-version documentation
        run: |
          poetry run python docs/scripts/build_multiversion.py _site
      - name: Generate latest alias
        run: |
          poetry run python docs/scripts/generate_latest_alias.py _site
      - name: Generate root redirect
        run: |
          poetry run python docs/scripts/generate_redirect.py _site
      - name: Copy CNAME to root
        run: |
          cp docs/CNAME _site/CNAME
      - name: Validate error messages documentation
        run: |
          # Verify error_messages.html was generated in at least one version
          if ! find _site/v* -name "error_messages.html" -type f 2>/dev/null | grep -q .; then
            echo "ERROR: No error_messages.html found in any version directory"
            exit 1
          fi
          # Check at least one file has content
          for file in _site/v*/error_messages.html; do
            if [ -f "$file" ] && [ -s "$file" ]; then
              echo "Error messages documentation validated successfully"
              exit 0
            fi
          done
          echo "ERROR: All error_messages.html files are empty"
          exit 1
      - name: Upload artifact
        # Automatically uploads an artifact from the './_site' directory by default
        uses: actions/upload-pages-artifact@v4

  # Deployment job
  deploy:
    if: always() && !cancelled() && needs.build.result == 'success'
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4