bottom/.github/workflows/docs.yml

# Workflow to deploy mkdocs documentation.

name: docs

on:
  workflow_dispatch:
  workflow_call:
    inputs:
      version:
        description: "The version to deploy."
        required: true
        type: string
      alias:
        description: "An optional alias to update."
        required: false
        type: string
  push:
    branches:
      - main
    paths:
      - "docs/**"
      - ".github/workflows/docs.yml"

permissions: {}

env:
  # Assign commit authorship to official GitHub Actions bot when pushing to the `gh-pages` branch:
  GIT_USER: "github-actions[bot]"
  GIT_EMAIL: "41898282+github-actions[bot]@users.noreply.github.com"

jobs:
  build-documentation:
    name: Build and deploy docs
    runs-on: ubuntu-24.04
    permissions:
      contents: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-depth: 0
          # This is required due to mike needing to push.
          persist-credentials: true

      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: 3.12

      - name: Install Python dependencies
        run: pip install -r docs/requirements.txt

      - name: Configure git user and email
        run: ./scripts/ci/configure_git.sh

      - name: Build and deploy docs with mike
        run: |
          cd docs
          if [[ -n "${INPUTS_ALIAS}" ]]; then
            mike deploy --push ${INPUTS_VERSION} --update-aliases ${INPUTS_ALIAS}
          elif [[ "${INPUTS_VERSION}" == "nightly" ]]; then
            mike deploy --push ${INPUTS_VERSION}
          else
            mike deploy --push nightly
          fi
        env:
          INPUTS_ALIAS: ${{ inputs.alias }}
          INPUTS_VERSION: ${{ inputs.version }}

  publish-gh-pages:
    needs: [build-documentation]
    permissions:
      pages: write
      id-token: write
    uses: ./.github/workflows/publish_github_pages.yml
    secrets: inherit