cd_docs.yml

name: CI/CD - Documentation

on:
  # Run for every push to the active development branch
  push:
    branches:
      - 'main'
      - 'push-action/**'  # For the CasperWA/push-protected action

  # Run for every new release
  release:
    types:
      - published

  # Run for every pull request (check we can build, but do not build)
  pull_request:
    branches:
      - 'main'

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write  # to deploy to Pages
  id-token: write  # to verify the deployment originates from an appropriate source

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

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

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5

      - name: Install dependencies
        run: |
          python -m pip install -U pip
          pip install -U setuptools wheel
          pip install -e .[docs]

      - name: Build documentation
        run: |
          mkdir -p docs/_static
          sphinx-build docs public -W

      - name: Upload artifacts
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    runs-on: ubuntu-latest

    if: github.event_name != 'pull_request' && ( ! startsWith(github.ref_name, 'push-action/') )

    needs: build

    # Allow only one concurrent deployment, skipping runs queued between the run
    # in-progress and latest queued.
    # However, do NOT cancel in-progress runs as we want to allow these production
    # deployments to complete.
    concurrency:
      group: "pages"
      cancel-in-progress: false

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

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