build-publish-docs.yaml

# This is a GitHub workflow defining a set of jobs with a set of steps.
# ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions
#
name: Build and publish documentation

on:
  pull_request:
    paths:
      - "docs/**"
      - "dask-gateway/**"
      - "dask-gateway-server/**"
      - ".github/workflows/build-publish-docs.yaml"
  push:
    paths:
      - "docs/**"
      - "dask-gateway/**"
      - "dask-gateway-server/**"
      - ".github/workflows/build-publish-docs.yaml"
    branches: ["main"]
    tags: ["**"]
  workflow_dispatch:

env:
  commit_msg: ${{ github.event.head_commit.message }}

jobs:
  build-and-publish-docs:
    name: Build and publish documentation
    runs-on: ubuntu-22.04

    # permissions requested for secrets.github_token in order to push to the
    # gh-pages branch, available for push and workflow_dispatch triggers.
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install Python docs requirements
        run: |
          DASK_GATEWAY_SERVER__NO_PROXY=true pip install -r docs/requirements.txt

      - name: Build docs (make html)
        run: |
          cd docs
          make html SPHINXOPTS='--color -W --keep-going'

      - name: Push built docs to gh-pages branch
        uses: JamesIves/github-pages-deploy-action@releases/v4
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        with:
          branch: gh-pages
          folder: docs/_build/html/

  linkcheck-docs:
    name: Test links in docs
    runs-on: ubuntu-22.04

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install Python docs requirements
        run: |
          DASK_GATEWAY_SERVER__NO_PROXY=true pip install -r docs/requirements.txt

      - name: Linkcheck docs (make linkcheck)
        run: |
          cd docs
          make linkcheck SPHINXOPTS='--color -W --keep-going'