Docs workflow (NVIDIA/tilus)

name: Docs
 
on:
  push:
    branches:
      - main
      - "pull-request/[0-9]+"
    tags:
      - "v*"
  workflow_dispatch:
 
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') && github.ref != 'refs/heads/main' }}
 
permissions:
  contents: write
 
jobs:
  build:
    timeout-minutes: 30
    if: github.repository == 'NVIDIA/tilus'
    runs-on: latchkey-small
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - name: Setup and Install Tilus
        id: setup-and-install
        uses: ./.github/actions/setup-environment
        with:
          python-version: '3.10'
 
      - name: Build docs
        run: |
          cd docs
          make html SPHINXOPTS="-W"  # -W treats warnings as errors
 
      - name: Upload docs artifact
        if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
        uses: actions/upload-artifact@v4
        with:
          name: docs-html
          path: docs/build/html/
 
  deploy:
    timeout-minutes: 30
    needs: build
    if: github.repository == 'NVIDIA/tilus' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
    runs-on: latchkey-small
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - name: Download docs artifact
        uses: actions/download-artifact@v4
        with:
          name: docs-html
          path: docs/build/html/
 
      - name: Determine version directory
        id: version
        run: |
          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
            VERSION="${GITHUB_REF#refs/tags/}"
            echo "dir=$VERSION" >> $GITHUB_OUTPUT
            echo "is_tag=true" >> $GITHUB_OUTPUT
          else
            echo "dir=latest" >> $GITHUB_OUTPUT
            echo "is_tag=false" >> $GITHUB_OUTPUT
          fi
 
      - name: Deploy to gh-pages
        run: |
          VERSION_DIR="${{ steps.version.outputs.dir }}"
          IS_TAG="${{ steps.version.outputs.is_tag }}"
 
          # Configure git
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
 
          # Clone the gh-pages branch (or create it if it doesn't exist)
          git fetch origin gh-pages:gh-pages 2>/dev/null || true
          DEPLOY_DIR=$(mktemp -d)
          if git rev-parse --verify gh-pages >/dev/null 2>&1; then
            git worktree add "$DEPLOY_DIR" gh-pages
          else
            # Create orphan gh-pages branch
            git checkout --orphan gh-pages
            git rm -rf . 2>/dev/null || true
            git commit --allow-empty -m "Initialize gh-pages"
            git checkout -
            git worktree add "$DEPLOY_DIR" gh-pages
          fi
 
          # Copy new build into versioned subdirectory
          rm -rf "$DEPLOY_DIR/$VERSION_DIR"
          cp -r docs/build/html "$DEPLOY_DIR/$VERSION_DIR"
 
          # For tag releases, also update the "stable" symlink
          if [[ "$IS_TAG" == "true" ]]; then
            rm -rf "$DEPLOY_DIR/stable"
            cp -r docs/build/html "$DEPLOY_DIR/stable"
          fi
 
          # Update versions.json and generate root index.html
          cd "$DEPLOY_DIR"
          TAG_FLAG=""
          if [[ "$IS_TAG" == "true" ]]; then TAG_FLAG="--is-tag"; fi
          python3 "$GITHUB_WORKSPACE/.github/workflows/scripts/update_gh_pages.py" \
            --version-dir "$VERSION_DIR" $TAG_FLAG
 
          # Add .nojekyll to prevent GitHub Pages from ignoring _static
          touch .nojekyll
 
          # Commit and push
          git add -A
          git diff --cached --quiet && echo "No changes to deploy" && exit 0
          MSG="Deploy docs: $VERSION_DIR ($(date -u +%Y-%m-%d))"
          PR_NUM=$(git log -1 --pretty=%s "$GITHUB_SHA" | grep -oE '#[0-9]+' | head -n 1 || true)
          if [[ -n "$PR_NUM" ]]; then
            MSG="$MSG $PR_NUM"
          fi
          git commit -m "$MSG"
          git push origin gh-pages