name: Build and Deploy Documentation

on:
  push:
    branches:
      - main
      - gear-sonic
    paths:
      - "docs/**"
      - ".github/workflows/docs.yml"
      - ".gitattributes"
  workflow_dispatch:

# Allow only one concurrent deployment; cancel in-flight runs
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    name: Build Sphinx Docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          lfs: false

      - name: Restore docs static assets (bypass git-lfs smudge)
        run: |
          # git-lfs on the runner rewrites files tracked by *.png/*.gif
          # even when our .gitattributes override removes filter=lfs.
          # Use git cat-file to write real binary content directly from
          # the object store, bypassing all smudge filters.
          git ls-tree -r HEAD -- docs/source/_static \
            | awk '{print $3, $4}' \
            | while IFS=" " read -r hash path; do
                git cat-file blob "$hash" > "$path"
              done

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"
          cache: "pip"
          cache-dependency-path: "docs/requirements.txt"

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

      - name: Build HTML documentation
        run: sphinx-build -b html docs/source docs/build/html

      - name: Upload Pages artifact
        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/gear-sonic'
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/build/html

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/gear-sonic'
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4