docs-build.yml

name: Build Docs

on:
  push:
    branches: ["master", "release/*"]
    tags: ["*"]
  pull_request:
    branches: ["master", "release/*"]
    types: [opened, reopened, ready_for_review, synchronize]

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: "_ci-cache_PyPI"
  PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION: "python"
  TOKENIZERS_PARALLELISM: false
  SPHINX_MOCK_REQUIREMENTS: 0
  SPHINX_FETCH_ASSETS: 0

jobs:
  docs-make:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-22.04
    strategy:
      fail-fast: false
      matrix:
        check: [html, doctest, linkcheck]
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: "3.9"

      - name: source cashing
        uses: ./.github/actions/pull-caches
        with:
          requires: ${{ matrix.requires }}
          pytorch-version: ${{ matrix.pytorch-version }}
          pypi-dir: ${{ env.PYPI_CACHE }}

      - name: Install Latex
        if: ${{ matrix.check == 'html' }}
        # install Texlive, see https://linuxconfig.org/how-to-install-latex-on-ubuntu-20-04-focal-fossa-linux
        run: |
          sudo apt-get update --fix-missing
          sudo apt-get install -y \
            texlive-latex-extra texlive-pictures texlive-fonts-recommended dvipng cm-super

      - name: Pull sphinx template
        run: |
          pip install awscli
          aws s3 sync --no-sign-request s3://sphinx-packages/ dist/
      - name: Install package & dependencies
        run: |
          sudo apt-get update --fix-missing
          sudo apt-get install -y cmake
          pip --version
          pip install . -U -r requirements/docs.txt \
            --find-links="${PYPI_CACHE}" --find-links="${TORCH_URL}" --find-links="dist/"
          pip list

      - name: Test Examples in Documentation
        if: ${{ matrix.check == 'doctest' }}
        working-directory: ./docs
        run: |
          make doctest
          make coverage

      - name: Check External Links
        if: ${{ matrix.check == 'linkcheck' }}
        working-directory: ./docs
        env:
          SPHINX_MOCK_REQUIREMENTS: 1
        run: make --jobs $(nproc) linkcheck SPHINXOPTS="--keep-going"

      - name: Full build for deployment
        if: github.event_name == 'push'
        run: echo "SPHINX_FETCH_ASSETS=1" >> $GITHUB_ENV
      - name: Make Documentation
        if: ${{ matrix.check == 'html' }}
        working-directory: ./docs
        run: make html --debug SPHINXOPTS="-W --keep-going"

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

      - name: update cashing
        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
        continue-on-error: true
        uses: ./.github/actions/push-caches
        with:
          pypi-dir: ${{ env.PYPI_CACHE }}

  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-metrics"
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: docs-${{ github.sha }}
          path: docs/build/

      - 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/metrics/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/metrics/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/metrics/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}