docs.yml

name: Docs

on:
  push:
    branches-ignore:
      # These should always correspond to pull requests, so ignore them for
      # the push trigger and let them be triggered by the pull_request
      # trigger, avoiding running the workflow twice.  This is a minor
      # optimization so there's no need to ensure this is comprehensive.
      - 'dependabot/**'

  # The branches below must be a subset of the branches above
  pull_request:
    branches:
      - develop
      - main

jobs:
  docs:
    runs-on: ubuntu-latest
    name: Build and test package documentation

    # The maximum number of minutes to let a workflow run
    # before GitHub automatically cancels it. Default: 360
    timeout-minutes: 30

    steps:
      - name: Checkout code
        uses: actions/checkout@v4.1.1

      - name: Set up Python 3.12
        uses: actions/setup-python@v5.3.0
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install tox tox-gh-actions setuptools

      - name: Check external links in the package documentation
        run: tox -e linkcheck

      - name: Build and test package documentation
        run: tox -e docs

      - name: Archive docs artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: docs
          path: docs
          # Artifacts are retained for 90 days by default.
          # In fact, we don't need such long period.
          retention-days: 60