lightning/.github/workflows/docs-build.yml

name: Docs builds
# https://github.com/marketplace/actions/sphinx-build

on:
  push:
    branches: ["master", "release/*"]
    tags: ["*"]
  pull_request:
    branches: ["master", "release/*"]
    types: [opened, reopened, ready_for_review, synchronize]  # added `ready_for_review` since draft is skipped
    paths:
      - ".actions/*"
      - ".github/workflows/docs-build.yml"
      - "requirements/**"
      - "docs/**"
      - "src/**"
      - "setup.py"
      - "pyproject.toml"  # includes metadata used in the package creation
      - "!*.md"
      - "!**/*.md"

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.head_ref }}
  cancel-in-progress: ${{ ! (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/heads/release/')) }}

defaults:
  run:
    shell: bash

env:
  FREEZE_REQUIREMENTS: "1"
  TORCH_URL: "https://download.pytorch.org/whl/cpu/torch_stable.html"
  PYPI_CACHE_DIR: "_pip-wheels"
  PYPI_LOCAL_DIR: "pypi_pkgs/"

jobs:
  docs-make:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-20.04
    strategy:
      fail-fast: false
      matrix:
        pkg-name: ["app", "fabric", "pytorch"]
        check: ["html", "doctest", "linkcheck"]
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
      - uses: actions/setup-python@v4
        with:
          python-version: "3.9"

      - name: Pull sphinx template
        run: |
          pip install awscli
          aws s3 sync --no-sign-request s3://sphinx-packages/ ${PYPI_LOCAL_DIR}

      - name: pip wheels cache
        uses: actions/cache/restore@v3
        with:
          path: ${{ env.PYPI_CACHE_DIR }}
          key: pypi_wheels

      - name: Install pandoc & texlive
        if: ${{ matrix.pkg-name == 'pytorch' }}
        run: |
          sudo apt-get update
          sudo apt-get install -y pandoc texlive-latex-extra dvipng texlive-pictures
      - name: Install package & dependencies
        run: |
          mkdir -p ${PYPI_CACHE_DIR}  # in case cache was not hit
          ls -lh ${PYPI_CACHE_DIR}
          mkdir -p ${PYPI_LOCAL_DIR}  # in case template is not pulled
          pip install .[all] -U -r requirements/${{ matrix.pkg-name }}/docs.txt \
            -f ${PYPI_LOCAL_DIR} -f ${PYPI_CACHE_DIR} -f ${TORCH_URL}
          pip list

      - name: Test Examples in Docs
        if: ${{ matrix.check == 'doctest' }}
        working-directory: ./docs/source-${{ matrix.pkg-name }}
        env:
          FAST_DOCS_DEV: 1
        run: |
          make doctest
          make coverage

      - name: Check External Links
        if: ${{ matrix.check == 'linkcheck' }}
        working-directory: ./docs/source-${{ matrix.pkg-name }}
        env:
          FAST_DOCS_DEV: 1
        run: make linkcheck SPHINXOPTS="--keep-going"

      - name: Make Documentation
        if: ${{ matrix.check == 'html' }}
        working-directory: ./docs/source-${{ matrix.pkg-name }}
        env:
          FAST_DOCS_DEV: 0
        run: make html --debug --jobs $(nproc) SPHINXOPTS="-W --keep-going"

      - name: Keep artifact
        id: keep-artifact
        run: python -c "print('DAYS=' + str(7 if '${{ github.event_name }}'.startswith('pull_request') else 0))" >> $GITHUB_OUTPUT

      - name: Upload built docs
        if: ${{ matrix.check == 'html' }}
        uses: actions/upload-artifact@v3
        with:
          name: docs-${{ matrix.pkg-name }}-${{ github.sha }}
          path: docs/build/html/
          retention-days: ${{ steps.keep-artifact.outputs.DAYS }}

      - name: Dump handy wheels
        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
        continue-on-error: true
        uses: ./.github/actions/pip-wheels
        with:
          wheel-dir: ${{ env.PYPI_CACHE_DIR }}
          torch-url: ${{ env.TORCH_URL }}
          cache-key: "pypi_wheels"

  deploy-docs:
    needs: docs-make
    if: github.repository_owner == 'Lightning-AI' && github.event_name == 'push'
    runs-on: ubuntu-20.04
    strategy:
      fail-fast: false
      matrix:
        pkg-name: ["app", "fabric", "pytorch"]
    env:
      GCP_TARGET: "gs://lightning-docs-${{ matrix.pkg-name }}"
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: docs-${{ matrix.pkg-name }}-${{ github.sha }}
          path: docs/build/html/

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

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

      # Uploading docs to GCS, so they can be served on lightning.ai
      - name: Upload docs/${{ matrix.pkg-name }}/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/${{ matrix.pkg-name }}/latest to GCS 🪣
        if: github.ref == 'refs/heads/master'
        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/${{ matrix.pkg-name }}/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}