doc-deploy.yml

name: Build and Deploy MkDocs

on:
  push:
    branches:
      - master
    paths:
      - docs/**                         # Any change in documentation
      - .github/workflows/doc-deploy.yml # Any change in this workflow

# Set required permissions for GitHub Pages deployment
permissions:
  contents: read       # Allow reading repository contents
  pages: write         # Allow writing to GitHub Pages
  id-token: write      # Required for OIDC authentication to deploy

# Avoid concurrent deployments on the same branch
concurrency:
  group: pages-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # Checkout the repository at the pushed commit
      - name: Checkout repository
        uses: actions/checkout@v4

      # Setup Python
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.13'

      # Install Python dependencies for MkDocs
      - name: Install dependencies
        run: |
          echo "Installing MkDocs dependencies"
          pip install -r docs/requirements.txt

      # Build MkDocs site
      - name: Build MkDocs site
        run: |
          echo "Building MkDocs site"
          cd docs
          # Clean previous 'master' build
          rm -rf site/master
          # Build the site into 'site/master'
          mkdocs build --site-dir site/master

      # Upload the built static files as an artifact for GitHub Pages
      - name: Upload static files as artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Path to the directory containing the built site
          path: docs/site

  deploy:
    # Ensure 'deploy' only runs after 'build' completes successfully
    needs: build
    runs-on: ubuntu-latest

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages

    steps:
      # Deploy the uploaded artifact to GitHub Pages
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4