docs.yml

name: Deploy Documentation to GitHub Pages

on:
  push:
    branches: [ main, master]
    paths:
      - 'docs/**'
      - '**/*.md'
      - '.github/workflows/docs.yml'
  pull_request:
    branches: [ main, master ]
    paths:
      - 'docs/**'
      - '**/*.md'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

permissions:
  contents: write

env:
  # Set to 'false' to allow external link failures without failing the build
  # Configure via: Settings → Secrets and variables → Actions → Variables → New repository variable ->
  # Name: FAIL_ON_BROKEN_LINKS, Value: false
  FAIL_ON_BROKEN_LINKS: ${{ vars.FAIL_ON_BROKEN_LINKS == 'true' }}

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

jobs:
  link-validation:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Check Internal Links
        uses: becheran/mlc@v1.2.0
        with:
          # Only check local/internal links - these must pass
          args: --offline .

      - name: Check External Links
        run: |
          # Install mlc
          curl -sLO https://github.com/becheran/mlc/releases/download/v1.2.0/mlc-x86_64-linux
          chmod +x mlc-x86_64-linux
          sudo mv mlc-x86_64-linux /usr/local/bin/mlc
          
          # Run external link check and capture output
          set +e
          OUTPUT=$(mlc . 2>&1)
          EXIT_CODE=$?
          set -e
          echo "$OUTPUT"
          if [ $EXIT_CODE -eq 0 ]; then
            echo "✅ All external links are valid"
          else
            echo "FAIL_ON_BROKEN_LINKS value: '$FAIL_ON_BROKEN_LINKS'"
            if [ "$FAIL_ON_BROKEN_LINKS" == "true" ]; then
              echo "❌ External link check failed. See broken links above."
              exit 1
            else
              echo "::warning::Some external links may be broken (FAIL_ON_BROKEN_LINKS=false, continuing)"
            fi
          fi
        shell: bash

  # Build job for PRs - just validates the docs build
  build-pr:
    if: github.event_name == 'pull_request'
    needs: link-validation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Cache pip dependencies
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('docs/requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      - name: Install dependencies
        run: |
          pip install -r docs/requirements.txt

      - name: Build documentation
        run: |
          cd docs
          mkdocs build --strict

      - name: Summary
        run: |
          echo "✅ Documentation built successfully!" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "The documentation has been validated and builds without errors." >> $GITHUB_STEP_SUMMARY

  # Deploy job for main/master branch - deploys as 'dev' version
  deploy:
    if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Fetch all history for mike

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Cache pip dependencies
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('docs/requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      - name: Install dependencies
        run: |
          pip install -r docs/requirements.txt

      - name: Configure Git
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"

      - name: Deploy dev version with mike (hidden)
        run: |
          cd docs
          # Deploy as 'dev' version (main branch development docs)
          # Note: 'dev' is intentionally not added to any alias to keep it hidden from the version selector
          # Users can still access it directly at /dev/ but it won't show in the dropdown
          mike deploy --push dev --prop-set "hidden=true"
          # Ensure dev does NOT appear in version selector by not aliasing it

      - name: Summary
        run: |
          echo "✅ Development documentation deployed!" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "- Version: \`dev\` (hidden from version selector)" >> $GITHUB_STEP_SUMMARY
          echo "- Branch: \`gh-pages\`" >> $GITHUB_STEP_SUMMARY
          echo "- URL: https://opendatahub-io.github.io/models-as-a-service/dev/" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "ℹ️ The dev version is accessible directly but won't appear in the version dropdown." >> $GITHUB_STEP_SUMMARY