docs-build.yml

name: "Build (& deploy) Docs"
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, reopened, ready_for_review, synchronize]
  workflow_dispatch: {}

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.head_ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

defaults:
  run:
    shell: bash

jobs:
  docs-make:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-22.04
    strategy:
      fail-fast: false
      matrix:
        target: ["html", "doctest", "linkcheck"]
    env:
      ARTIFACT_DAYS: 0
      PYPI_LOCAL_DIR: "pypi_pkgs/"
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      - name: Pull sphinx template
        run: make get-sphinx-theme
      - name: Install pandoc
        timeout-minutes: 5
        run: sudo apt-get install -y pandoc
      - name: Install package & dependencies
        timeout-minutes: 20
        run: pip install . -U -r requirements/docs.txt

      - name: Make ${{ matrix.target }}
        working-directory: docs/
        # allow failing link check and doctest if you run with dispatch
        continue-on-error: ${{ matrix.target == 'doctest' || matrix.target == 'linkcheck' }}
        run: make ${{ matrix.target }} --debug --jobs $(nproc) SPHINXOPTS="-W --keep-going"

      - name: Keep artifact
        if: github.event_name == 'pull_request'
        run: echo "ARTIFACT_DAYS=7" >> $GITHUB_ENV
      - name: Upload built docs
        if: ${{ matrix.target == 'html' }}
        uses: actions/upload-artifact@v4
        with:
          name: docs-html-${{ github.sha }}
          path: docs/build/html/
          retention-days: ${{ env.ARTIFACT_DAYS }}

  deploy-docs:
    needs: docs-make
    if: github.repository_owner == 'Lightning-AI' && github.event_name == 'push'
    runs-on: ubuntu-latest
    env:
      GCP_TARGET: "gs://lightning-docs-thunder"
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: docs-html-${{ github.sha }}
          path: docs/build/html/

      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v2
        with:
          credentials_json: ${{ secrets.GCS_SA_KEY }}

      - name: Setup gcloud
        uses: google-github-actions/setup-gcloud@v2
        with:
          project_id: ${{ secrets.GCS_PROJECT }}

      # Uploading docs to GCS, so they can be served on lightning.ai
      #- name: Upload docs/thunder/stable to GCS 🪣
      #  if: startsWith(github.ref, 'refs/heads/release/')
      #  run: gsutil -m rsync -d -R docs/build/html/ ${GCP_TARGET}/stable

      # Uploading docs to GCS, so they can be served on lightning.ai
      - name: Upload docs/thunder/latest to GCS 🪣
        if: github.ref == 'refs/heads/main'
        run: gsutil -m rsync -d -R docs/build/html/ ${GCP_TARGET}/latest

      # Uploading docs to GCS, so they can be served on lightning.ai
      #- name: Upload docs/thunder/release to GCS 🪣
      #  if: startsWith(github.ref, 'refs/tags/')
      #  run: gsutil -m rsync -d -R docs/build/html/ ${GCP_TARGET}/${{ github.ref_name }}

      # Uploading docs as archive to GCS, so they can be as backup
      #- name: Upload docs as archive to GCS 🪣
      #  if: startsWith(github.ref, 'refs/tags/')
      #  working-directory: docs/build
      #  run: |
      #    zip ${{ github.ref_name }}.zip -r html/
      #    gsutil cp ${{ github.ref_name }}.zip ${GCP_TARGET}