docs.yaml

name: Build Docs

on:
  workflow_dispatch:
  workflow_call:

jobs:
  latest-build:
    # We only need to verify that the docs build with no warnings here
    name: Build Latest Docs Version
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Python Dependencies
        uses: HassanAbouelela/actions/setup-python@setup-python_v1.4.2
        with:
          python_version: "3.11"
          install_args: "--extras async-rediscache --only main --only doc"

      - name: Generate HTML Site
        run: sphinx-build -nW -j auto -b html docs docs/build

      - name: Upload Build Artifact
        uses: actions/upload-artifact@v4
        with:
          name: docs-latest
          path: docs/build/*

  build-deploy:
    name: Build & Deploy Docs
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # We need to check out the entire repository to find all tags

      - name: Install Python Dependencies
        uses: HassanAbouelela/actions/setup-python@setup-python_v1.4.2
        with:
          python_version: "3.11"
          install_args: "--extras async-rediscache"

      - name: Build All Doc Versions
        run: sphinx-multiversion docs docs/build -n -j auto
        env:
          BUILD_DOCS_FOR_HEAD: ${{ github.event_name == 'pull_request' }}
          BRANCH_NAME: ${{ github.head_ref }}

      - name: Remove Metadata Files
        run: |
          rm -r docs/build/**/_sources
          rm -r docs/build/**/.doctrees

      - name: Upload Build Artifact
        uses: actions/upload-artifact@v4
        with:
          name: docs
          path: docs/build/*

      - name: Deploy To GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: docs
          folder: docs/build
          # We only want to actually push the build if we're on main, otherwise just make sure everything works
          dry-run: ${{ github.ref != 'refs/heads/main' }}