docs-build.yml

name: Build Docs

on:
  push:
    branches: ["master", "release/*"]
    tags: ["*"]
  pull_request:
    branches: ["master", "release/*"]

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_FETCH_ASSETS: 1  # todo: consider not downloading on PRs

jobs:
  docs-check:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-22.04
    strategy:
      fail-fast: false
      matrix:
        check: [doctest, linkcheck]
    env:
      SPHINX_MOCK_REQUIREMENTS: 0
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v3
      - 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 package & dependencies
        run: |
          sudo apt-get update && sudo apt-get install -y cmake
          pip --version
          pip install . -U -r requirements/docs.txt --find-links $PYPI_CACHE -f $TORCH_URL
          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
        run: make --jobs $(nproc) linkcheck SPHINXOPTS="--keep-going"
        # ToDO: comment on PR if any link failed
        #continue-on-error: true


  make-html:
    runs-on: ubuntu-22.04
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v3
      - 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 }}

      # Note: This uses an internal pip API and may not always work
      # https://github.com/actions/cache/blob/master/examples.md#multiple-oss-in-a-workflow
      - name: Cache pip
        uses: actions/cache@v3
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}-${{ hashFiles('requirements/docs.txt') }}
          restore-keys: ${{ runner.os }}-pip-

      - name: Install dependencies & package
        run: |
          # install Texlive, see https://linuxconfig.org/how-to-install-latex-on-ubuntu-20-04-focal-fossa-linux
          sudo apt-get update
          sudo apt-get install -y texlive-latex-extra dvipng texlive-pictures texlive-fonts-recommended cm-super
          pip --version
          pip install . -U -r requirements/docs.txt --find-links $PYPI_CACHE -f $TORCH_URL
          pip list
        shell: bash

      - name: Make Documentation
        working-directory: ./docs
        run: make html --debug SPHINXOPTS="-W --keep-going"

      - name: Upload built docs
        uses: actions/upload-artifact@v3
        if: github.event_name == 'push'
        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-check, make-html]
    if: github.repository_owner == 'Lightning-AI' && github.event_name == 'push'
    runs-on: ubuntu-latest
    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/ gs://lightning-docs-metrics/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/ gs://lightning-docs-metrics/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/ gs://lightning-docs-metrics/${{  github.ref_name }}