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

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

on:
  push:
    branches: ["master", "release/*"]
  # use this event type to share secrets with forks.
  # it's important that the PR head SHA is checked out to run the changes
  pull_request_target:
    branches: ["master", "release/*"]
    paths:
      - ".actions/**"
      - ".github/workflows/docs-checks.yml"
      - "requirements/**"
      - "docs/**"
      - "src/**"
      - "setup.py"
      - "setup.cfg"  # 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

jobs:
  make-doctest:
    runs-on: ubuntu-latest
    container:
      image: pytorchlightning/pytorch_lightning:docs
    strategy:
      fail-fast: false
      matrix:
        pkg-name: ["app", "pytorch"]
    env:
      FREEZE_REQUIREMENTS: "1"
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          ref: ${{ github.event.pull_request.head.sha }}

      - uses: aws-actions/configure-aws-credentials@v1
        if: ${{ matrix.pkg-name == 'app' }}
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_KEY_ID }}
          aws-region: us-east-1

      - run: aws s3 sync s3://sphinx-packages/ pypi/
        if: ${{ matrix.pkg-name == 'app' }}

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

      - name: Install LAI package
        # This is needed as App docs is heavily using/referring to lightning package
        if: ${{ matrix.pkg-name == 'app' }}
        run: |
          pip install -e . -U -v -f https://download.pytorch.org/whl/cpu/torch_stable.html -f pypi          

      - name: Adjust docs refs
        if: ${{ matrix.pkg-name == 'app' }}
        run: |
          pip install -q -r .actions/requirements.txt
          python .actions/assistant.py copy_replace_imports --source_dir="./docs" \
            --source_import="pytorch_lightning,lightning_fabric" \
            --target_import="lightning.pytorch,lightning.fabric"          

      - name: Install this package
        env:
          PACKAGE_NAME: ${{ matrix.pkg-name }}
        run: |
          pip install -e .[extra,cloud,ui] -U -r requirements/${{ matrix.pkg-name }}/docs.txt -f pypi
          pip list          

      - name: Test Documentation
        env:
          SPHINX_MOCK_REQUIREMENTS: 0
        working-directory: ./docs/source-${{ matrix.pkg-name }}
        run: |
          make doctest
          make coverage          

  make-html:
    runs-on: ubuntu-latest
    container:
      image: pytorchlightning/pytorch_lightning:docs
    strategy:
      fail-fast: false
      matrix:
        pkg-name: ["app", "pytorch"]
    env:
      FREEZE_REQUIREMENTS: "1"
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          ref: ${{ github.event.pull_request.head.sha }}

      - uses: aws-actions/configure-aws-credentials@v1
        if: ${{ matrix.pkg-name != 'pytorch' }}
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_KEY_ID }}
          aws-region: us-east-1

      - run: aws s3 sync s3://sphinx-packages/ pypi/
        if: ${{ matrix.pkg-name != 'pytorch' }}

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

      - name: Install package & dependencies
        env:
          PACKAGE_NAME: ${{ matrix.pkg-name }}
        run: |
          pip --version
          pip install -e . -U -r requirements/${{ matrix.pkg-name }}/docs.txt \
            -f https://download.pytorch.org/whl/cpu/torch_stable.html -f pypi
          pip list          
        shell: bash

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

      - name: Check External Links in Sphinx Documentation (Optional)
        working-directory: ./docs/source-${{ matrix.pkg-name }}
        run: |
          make linkcheck          
        continue-on-error: true

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