build_and_deploy.yml

# As much as possible, this file should be kept in sync with
# https://github.com/napari/napari/blob/main/.github/workflows/build_docs.yml
#
# Note this workflow is also triggered by
# https://github.com/napari/napari/blob/main/.github/workflows/deploy_docs.yml when a
# commit to `main` occurs in `napari/napari`

name: Build & Deploy PR Docs

on:
  push:
    branches:
      - main
    tags:
      - 'v*'
  pull_request:
    branches:
      - main
  workflow_dispatch:
    inputs:
      target_directory:
        description: 'The directory to deploy the docs to'
        required: true
        default: 'dev'

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build-and-upload:
    name: Build & Upload Artifact
    runs-on: ubuntu-latest
    steps:
      - name: Clone docs repo
        uses: actions/checkout@v4
        with:
          # place in '/home/runner/work/docs/docs/docs'
          path: docs  # place in a named directory

      - name: Clone main repo
        uses: actions/checkout@v4
        with:
          # place in '/home/runner/work/docs/docs/napari'
          path: napari  # place in a named directory
          repository: napari/napari
          # ensure version metadata is proper
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"
          cache-dependency-path: |
            napari/pyproject.toml

      - uses: tlambert03/setup-qt-libs@v1

      - name: Install Dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install "napari/[pyqt5, docs]"
        env:
          PIP_CONSTRAINT: ${{ github.workspace }}/napari/resources/constraints/constraints_py3.10_docs.txt

      - name: Testing
        run: |
          python -c 'import napari; print(napari.__version__)'
          python -c 'import napari.layers; print(napari.layers.__doc__)'

      - name: Create fallback videos
        run: |
          sudo apt-get update && sudo apt-get install -y ffmpeg
          cd docs
          make fallback-videos

      - name: Build Docs
        uses: aganders3/headless-gui@v2
        env:
          GOOGLE_CALENDAR_ID: ${{ secrets.GOOGLE_CALENDAR_ID }}
          GOOGLE_CALENDAR_API_KEY: ${{ secrets.GOOGLE_CALENDAR_API_KEY }}
          PIP_CONSTRAINT: ${{ github.workspace }}/napari/resources/constraints/constraints_py3.10_docs.txt
        with:
          # Runs in '/home/runner/work/docs/docs/docs'
          # Built HTML pages in '/home/runner/work/docs/docs/docs/docs/_build/html'
          run:  make -C docs html
          # skipping setup stops the action from running the default (tiling) window manager
          # the window manager is not necessary for docs builds at this time and it was causing
          # problems with screenshots (https://github.com/napari/docs/issues/285)
          linux-setup: "echo 'skip setup'"
          linux-teardown: "echo 'skip teardown'"

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: html
          path: docs/docs/_build/html/

  deploy:
    name: Download & Deploy Artifact
    needs: build-and-upload
    runs-on: ubuntu-latest
    # Working directory: '/home/runner/work/docs/docs'
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: html
          # Downloads to '/home/runner/work/docs/docs/html'
          path: html

      - name: Deploy Docs
        if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && (startsWith(github.ref, 'refs/tags/v') || startsWith(github.ref, 'refs/heads/main'))
        uses: peaceiris/actions-gh-pages@v4
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: napari/napari.github.io
          publish_dir: ./html
          publish_branch: gh-pages
          destination_dir: ${{ github.event.inputs.target_directory || 'dev' }}
          cname: napari.org