generate-docs.yml

# Generate PySceneDetect documentation and updates the gh-pages branch.
name: Generate Documentation

on:
  push:
    branches:
      - main            # docs/head
      - 'releases/**'   # docs/**
    paths:
      - 'docs/**'
  workflow_dispatch:

jobs:
  update_docs:
    runs-on: ubuntu-latest
    env:
      # TODO: Figure out a better way to handle figuring out what version /latest should be,
      # e.g. add a latest version file in main.
      scenedetect_docs_latest: '0.6.4'
      scenedetect_docs_dest: ''

    steps:
      - uses: actions/checkout@v4

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

      - name: Set Destination (Releases)
        if: ${{ contains(github.ref_name, 'releases') }}
        run: |
          echo "scenedetect_docs_dest=$(echo ${{ github.ref_name }} | cut -b 10-)" >> "$GITHUB_ENV"

      - name: Set Destination (Head)
        if: ${{ contains(github.ref_name, 'main') }}
        run: |
          echo "scenedetect_docs_dest=head" >> "$GITHUB_ENV"

      - name: Check Destination
        if: ${{ env.scenedetect_docs_dest == '' }}
        run: |
          echo "Failing build: destination must be set!"

      - name: Setup Environment
        run: |
          python -m pip install --upgrade pip build wheel virtualenv
          pip install -r docs/requirements.txt
          pip install -r dist/requirements_windows.txt
          git config --global user.name github-actions
          git config --global user.email github-actions@github.com

      - name: Generate Docs
        run: |
          sphinx-build -b html docs build

      - name: Update gh-pages Branch
        run: |
          git fetch origin gh-pages
          git checkout gh-pages
          git rm "docs/${{ env.scenedetect_docs_dest }}" -r -f --ignore-unmatch
          git add build/
          git mv build "docs/${{ env.scenedetect_docs_dest }}"

      - name: Update Latest
        if: ${{ env.scenedetect_docs_dest == env.scenedetect_docs_latest }}
        run: |
          git rm "docs/latest" -r -f --ignore-unmatch
          mkdir -p latest
          cp -r -f "docs/${{ env.scenedetect_docs_dest }}" docs/latest
          git add docs/latest
          echo "scenedetect_docs_dest='${{ env.scenedetect_docs_dest }} (latest)'" >> "$GITHUB_ENV"

      - name: Commit and Push
        run: |
          git commit -a -m "[docs] @${{ github.triggering_actor }}: Generate Documentation" \
            -m "Source: ${{ github.ref_name }} (${{ github.sha }})" \
            -m "Destination: ${{ env.scenedetect_docs_dest }}"
          git push