docs.yml

# This workflow is checks that the documentation can be built across multiple OSes, Python, and Sphinx versions.
# It also checks for broken links in the documentation and runs Lighthouse audits on the built site.

name: docs-checks

# Concurrency group that uses the workflow name and PR number if available
# or commit SHA as a fallback. If a new build is triggered under that
# concurrency group while a previous build is running it will be canceled.
# Repeated pushes to a PR will cancel all previous builds, while multiple
# merges to main will not cancel.
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: true

env:
  FORCE_COLOR: "1" # Make tools pretty
  DEFAULT_PYTHON_VERSION: "3.12" # keep in sync with tox.ini
  PIP_DISABLE_PIP_VERSION_CHECK: "1" # Don't check for pip updates

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - "*"
  # allows this to be used as a composite action in other workflows
  workflow_call:
  # allow manual triggering of the workflow, while debugging
  workflow_dispatch:

jobs:
  # Build our docs (PST) on major OSes and check for warnings
  build-site:
    name: "build PST docs"
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.12", "3.13"]
        include:
          # oldest Python version with the oldest Sphinx version
          - os: ubuntu-latest
            python-version: "3.9"
            sphinx-version: "6.1"
    runs-on: ${{ matrix.os }}
    steps:
      - name: "Checkout repository 🛎"
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
        with:
          persist-credentials: false

      - name: "Setup CI environment 🛠"
        uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1
        with:
          python-version: ${{ matrix.python-version }}
          pandoc: true
          graphviz: true

      - name: "Build docs and check for warnings 📖"
        shell: bash
        run: |
          # check if there is a specific Sphinx version to build with
          # example substitution: tox run -e py39-sphinx61-docs
          if [ -n "${{matrix.sphinx-version}}" ]; then
            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-docs
          # build with the default Sphinx version
          # example substitution: tox run -e py312-docs
          else
            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-docs
          fi

  # Run Lighthouse audits on the built site (kitchen-sink only)
  lighthouse-audit:
    needs: build-site
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout repository 🛎"
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
        with:
          persist-credentials: false

      - name: "Setup CI environment 🛠"
        uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1
        with:
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}

      - name: "Copy kitchen sink to a tiny site"
        run: |
          # ensuring proper scaping of the variable
          docs_dir="${DOCS_DIR}"
          mkdir -p $docs_dir/site
          cp -r docs/examples/kitchen-sink $docs_dir/site/kitchen-sink
          printf "Test\n====\n\n.. toctree::\n\n   kitchen-sink/index\n" > $docs_dir/site/index.rst
          echo 'html_theme = "pydata_sphinx_theme"' > $docs_dir/site/conf.py
          echo '.. toctree::\n   :glob:\n\n   *' >> $docs_dir/site/index.rst

          # build docs without checking for warnings
          python -Im tox run -e docs-no-checks
        env:
          DOCS_DIR: "audit"

      - name: "Audit with Lighthouse 🔦"
        uses: treosh/lighthouse-ci-action@v12
        with:
          configPath: ".github/workflows/lighthouserc.json"
          temporaryPublicStorage: true
          uploadArtifacts: true
          runs: 3 # Multiple runs to reduce variance

  # Check for broken links in our docs
  link-check:
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout repository 🛎"
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
        with:
          persist-credentials: false

      - name: "Setup CI environment 🛠"
        uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1

      - name: "Check for broken links 🔗"
        run: python -Im tox -e docs-linkcheck

      - name: "Upload file with broken links 📤"
        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08
        with:
          name: broken-links
          path: docs/_build/linkcheck/output.txt
        if: ${{ always() }}