name: Build & publish docs (rc + release)

on:
  push:
    tags:
      - "rc*"
      - "v*"
  workflow_dispatch:

permissions:
  contents: read

env:
  MKDOCS_CONFIG: mkdocs/mkdocs.yml
  MKDOCS_OUTPUT_DIR: ${{ runner.temp }}/dist
  MKDOCS_STRICT: ${{ vars.MKDOCS_STRICT || 'true' }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install deps
        run: |
          set -euo pipefail
          pip install -r mkdocs/requirements.txt

      - name: Build docs (strict gate)
        run: |
          set -euo pipefail

          FLAGS=()
          if [ "${MKDOCS_STRICT}" = "true" ]; then
            FLAGS+=(--strict)
          fi

          mkdir -p "${MKDOCS_OUTPUT_DIR}"

          OFFLINE="${OFFLINE:-true}" mkdocs build \
            "${FLAGS[@]}" \
            -f "${MKDOCS_CONFIG}" \
            -d "${MKDOCS_OUTPUT_DIR}/offline"
            mkdocs build \
            "${FLAGS[@]}" \
            -f "${MKDOCS_CONFIG}" \
            -d "${MKDOCS_OUTPUT_DIR}/dist"

      - name: Zip site
        run: |
          set -euo pipefail
          cd "${MKDOCS_OUTPUT_DIR}"
          zip -r "${GITHUB_REF_NAME}.zip" "./offline"
  release:
    runs-on: ubuntu-latest
    needs: build
    steps:
      # -------------------------
      # RC-only step
      # -------------------------
      - name: Publish prerelease 
        if: startsWith(github.ref_name, 'rc')
        uses: softprops/action-gh-release@v2
        with:
          prerelease: true
          name: ${{ github.ref_name }}
          tag_name: ${{ github.ref_name }}
          body: |
            Release candidate preview (if deployed): /rc/
          files: |
            ${{ runner.temp }}/${{ github.ref_name }}.zip

      # -------------------------
      # Final release-only step
      # -------------------------
      - name: Publish release
        if: startsWith(github.ref_name, 'v')
        uses: softprops/action-gh-release@v2
        with:
          name: ${{ github.ref_name }}
          tag_name: ${{ github.ref_name }}
          files: |
            ${{ runner.temp }}/${{ github.ref_name }}.zip
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Checkout (tag)
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Checkout gh-pages branch
        run: |
          set -euo pipefail
          git fetch origin gh-pages:gh-pages || true
          if git show-ref --verify --quiet refs/heads/gh-pages; then
            git switch gh-pages
          else
            git switch --orphan gh-pages
            rm -rf ./*
            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git commit --allow-empty -m "Initialize gh-pages"
          fi

      - name: Publish release
        run: |
          set -euo pipefail
          rm -rf assets styles search *{.html,.xml,xml.gz} || true
          cp -a "${MKDOCS_OUTPUT_DIR}/dist/." ""

          git add -A
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git commit -m "Deploy release ${GITHUB_REF_NAME}" || echo "No changes to commit"
          git push origin gh-pages

      - name: Publish RC preview under /rc/<tag>/
        run: |
          set -euo pipefail
          rm -rf "rc"* || true
          mkdir -p "rc/"
          cp -a "${MKDOCS_OUTPUT_DIR}/dist/." "rc/"

          git add -A
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git commit -m "Deploy RC preview ${GITHUB_REF_NAME}" || echo "No changes to commit"
          git push origin gh-pages