docs.yml

name: Documentation

# Publishes versioned DocFX docs to the gh-pages branch:
#   * push to main          -> "main" pre-release docs   (default: false)
#   * called from release   -> the released version, made the site default
#   * manual dispatch        -> rebuild an arbitrary slug
# GitHub Pages must be configured to deploy from the gh-pages branch (root).
on:
  push:
    branches: [ "main" ]
    paths:
      - 'src/**'
      - 'docs/**'
      - '.github/workflows/docs.yml'
      - 'eng/deploy-docs.sh'
      - 'eng/update_versions.py'
  workflow_dispatch:
    inputs:
      slug:
        description: 'Path segment to publish under (e.g. main)'
        default: main
        type: string
      make_default:
        description: 'Point the site root at this slug'
        default: false
        type: boolean
  workflow_call:
    inputs:
      slug:
        required: true
        type: string
      make_default:
        required: false
        default: false
        type: boolean

permissions:
  contents: write

concurrency:
  group: docs-deploy
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    # This job also budgets for being invoked via workflow_call from
    # release.yml's `docs` job -- a caller job that uses a reusable workflow
    # cannot itself declare timeout-minutes, so this is the one place that
    # bounds both the standalone and the release-triggered run.
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: ./.github/actions/setup-build

      - name: Build documentation
        run: dotnet tool run docfx docs/docfx.json

      - name: Publish to gh-pages
        env:
          SLUG: ${{ inputs.slug || 'main' }}
          MAKE_DEFAULT: ${{ inputs.make_default || 'false' }}
        run: bash eng/deploy-docs.sh