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

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

on:
  push:
    branches: [master, "release/*"]
  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/')) }}

jobs:
  make-doctest:
    runs-on: ubuntu-20.04
    needs: make-html  # make it depending on build docs to reduce load
    strategy:
      fail-fast: false
      matrix:
        pkg: ["app", "pytorch"]  # TODO: , "lit"
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
      - uses: actions/setup-python@v4
        with:
          python-version: 3.9

      # 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 }}-docs-test-pip-${{ hashFiles('requirements/${{ matrix.pkg }}/*.txt') }}
          restore-keys: |
            ${{ runner.os }}-docs-test-pip-

      - name: Install package
        env:
          FREEZE_REQUIREMENTS: 1
          PACKAGE_NAME: ${{ matrix.pkg }}
        run: |
          sudo apt-get update
          sudo apt-get install -y cmake pandoc
          pip --version
          # python -m pip install --upgrade --user pip
          pip install -e . \
            -r requirements/${{ matrix.pkg }}/docs.txt \
            --find-links https://download.pytorch.org/whl/cpu/torch_stable.html
          pip list
        shell: bash

      - name: Install dependencies
        env:
          FREEZE_REQUIREMENTS: 1
          PACKAGE_NAME: pytorch
        run: |
          pip install -r requirements/${{ matrix.pkg }}/devel.txt \
            --find-links https://download.pytorch.org/whl/cpu/torch_stable.html
          pip list
        shell: bash

      - name: Test Documentation
        env:
          SPHINX_MOCK_REQUIREMENTS: 0
        working-directory: ./docs/source-${{ matrix.pkg }}
        run: |
          # ToDo: proper parametrize
          # First run the same pipeline as Read-The-Docs
          make doctest
          make coverage

  make-html:
    runs-on: ubuntu-20.04
    strategy:
      fail-fast: false
      matrix:
        pkg: ["app", "pytorch", "lit"]
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          # lfs: true
      - uses: actions/setup-python@v4
        with:
          python-version: 3.9

      # 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 }}-docs-make-pip-${{ hashFiles('requirements/${{ matrix.pkg }}/*.txt') }}
          restore-keys: |
            ${{ runner.os }}-docs-make-pip-

      - name: Install dependencies
        env:
          FREEZE_REQUIREMENTS: 1
        run: |
          sudo apt-get update
          sudo apt-get install -y cmake pandoc texlive-latex-extra dvipng texlive-pictures
          pip --version
          pip install -e . --quiet -r requirements/${{ matrix.pkg }}/docs.txt --find-links https://download.pytorch.org/whl/cpu/torch_stable.html
          pip list
        shell: bash

      - name: Make Documentation
        working-directory: ./docs/source-${{ matrix.pkg }}
        run: |
          # ToDo: rather use python cmd
          # First run the same pipeline as Read-The-Docs
          make html --debug --jobs $(nproc) SPHINXOPTS="-W --keep-going"

      - name: Upload built docs
        uses: actions/upload-artifact@v3
        with:
          name: docs-${{ matrix.pkg }}-${{ github.sha }}
          path: docs/build/html/
        # Use always() to always run this step to publish test results when there are test failures
        if: success()