_docs.yml

# ─────────────────────────────────────────────────────────────────────────────
# _docs.yml — Reusable Documentation Builder & Deployer
#
# Builds static documentation using MkDocs and Mike for versioning, and
# deploys it to GitHub Pages.
#
# Inputs:
#   build_type (required): "dev-branch", "dev", "nightly", "release", or "post"
#   alias (required):      The alias to use for the deployment (e.g., "latest", "nightly")
#
# Outputs:
#   deployed_url — The URL/path where the docs were deployed
#
# Callers: development.yml, nightly.yml, release.yml
# ─────────────────────────────────────────────────────────────────────────────
name: "Docs Builder & Deployer (Reusable)"

on:
  workflow_call:
    inputs:
      build_type:
        description: "Deploy target type: dev-branch, dev, nightly, release, or post"
        required: true
        type: string
      alias:
        description: "The alias to use for the documentation version (e.g., latest, nightly)"
        required: true
        type: string
    outputs:
      deployed_url:
        description: "Path where the docs were deployed"
        value: ${{ jobs.build-and-deploy-docs.outputs.deployed_url }}

permissions:
  contents: write       # Push to gh-pages branch

jobs:

  build-and-deploy-docs:
    name: "Build & Deploy Docs (${{ inputs.build_type }})"
    runs-on: ubuntu-latest
    outputs:
      deployed_url: ${{ steps.dest.outputs.path }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: "3.x"

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

      - name: Install MkDocs and dependencies
        run: |
          # Install standard mkdocs, material theme, and mike for versioning
          pip install mkdocs-material mike
          # Install any other requirements if they exist
          if [ -f docs/requirements.txt ]; then pip install -r docs/requirements.txt; fi

      - name: Compute deployment destination path
        id: dest
        run: |
          case "${{ inputs.build_type }}" in
            dev-branch) echo "path=pr-${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" ;;
            dev)        echo "path=dev"                        >> "$GITHUB_OUTPUT" ;;
            nightly)    echo "path=nightly"                    >> "$GITHUB_OUTPUT" ;;
            release)    echo "path=${{ github.ref_name }}"     >> "$GITHUB_OUTPUT" ;;
            post)       echo "path=post"                       >> "$GITHUB_OUTPUT" ;;
            *)          echo "path=${{ inputs.alias }}"        >> "$GITHUB_OUTPUT" ;;
          esac

      - name: Build and deploy using Mike
        run: |
          VERSION_PATH="${{ steps.dest.outputs.path }}"
          ALIAS="${{ inputs.alias }}"
          
          # Use mike to deploy to gh-pages branch
          # --push: push to origin
          # --update-aliases: update the alias pointer
          if [ "$ALIAS" != "" ] && [ "$ALIAS" != "$VERSION_PATH" ]; then
            mike deploy --push --update-aliases $VERSION_PATH $ALIAS
          else
            mike deploy --push $VERSION_PATH
          fi
          
          # If release, also set it as default
          if [ "${{ inputs.build_type }}" == "release" ]; then
            mike set-default --push $ALIAS
          fi