.github/workflows/javadoc.yml

name: Deploy Versioned Javadoc (Manual Trigger)

# Select the target TAG where to run the workflow from.
# This TAG name becomes the subdirectory under branch gh-pages/docs/${TAG}
#   where the javadocs will be copied to.

on:
  workflow_dispatch:
    inputs:
      tag_ref:
        description: 'Existing Git Tag to deploy (e.g., 1.0.0):'
        required: true
	default: '99.0.0' # unlikely to conflict if accidentally used. Can be left blank

jobs:
  build-and-deploy-javadoc:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout Code at Specified Tag
        uses: actions/checkout@v5
        with:
          ref: ${{ github.event.inputs.tag_ref }}  # from manual trigger input
          fetch-depth: 0

      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          java-version: '25'
          distribution: 'temurin'
          cache: 'maven'

      - name: Build and Generate Javadoc  # POM is configured to output to target/site/apidocs
        run: mvn javadoc:javadoc

      - name: Deploy Javadoc via Worktree
        env:
          TAG_NAME: ${{ github.event.inputs.tag_ref }}
        run: |
          # 1. Initialize error tracking
          EXIT_CODE=0
          
          # 2. Configure Git Identity
          git config user.email "noreply@github.com"
          git config user.name "github-actions[bot]"
          
          # 3. Ensure gh-pages exists and is fetched
          git fetch origin gh-pages --depth=1 || git branch gh-pages
          
          # 4. Create worktree for the gh-pages branch in a separate folder
          git worktree add ./gh-pages-dir origin/gh-pages
          
          # 5. Deployment Logic in a subshell to capture exit code
          (
            set -e # Exit subshell on any internal error
            TARGET_PATH="gh-pages-dir/docs/$TAG_NAME" # target directory inside the worktree
            mkdir -p "$TARGET_PATH"
            cp -a target/site/apidocs/. "$TARGET_PATH/"
            
            cd gh-pages-dir
            git add .
            
            if git diff --staged --quiet; then
              echo "No changes detected for Javadoc $TAG_NAME."
            else
              git commit -m "Manual Javadoc deployment for tag $TAG_NAME"
              git push origin gh-pages
            fi
          ) || EXIT_CODE=$?
          
          # 6. Cleanup (Always runs)
          echo "Cleaning up worktree..."
          git worktree remove --force ./gh-pages-dir || true
          
          # 7. Final exit based on subshell success
          exit $EXIT_CODE

      - name: Confirm Deployment
        if: success()
        run: echo "Javadoc for ${{ github.event.inputs.tag_ref }} is now live on gh-pages."