name: "Documentation"

on:
  push:
    branches: [ main ]
  pull_request: ~
  workflow_dispatch:

# Cancel redundant in-progress jobs.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:

  documentation:
    name: "Documentation: Python ${{ matrix.python-version }} on ${{ matrix.os }}"
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: ["ubuntu-latest"]
        python-version: ["3.13"]
    env:
      UV_SYSTEM_PYTHON: true

    steps:
    - uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.python-version }}

    - name: Set up uv
      uses: astral-sh/setup-uv@v5
      with:
        version: "latest"
        enable-cache: true
        cache-suffix: ${{ matrix.python-version }}
        cache-dependency-glob: |
          pyproject.toml

    - name: Install package and documentation dependencies
      run: |
        uv pip install '.[develop,docs]'

    - name: Run link checker
      run: |
        poe docs-linkcheck

    - name: Build static HTML documentation
      run: |
        poe docs-html