tests.yml

name: ci

on:
  push:
  pull_request:

jobs:
  qa:
    runs-on: ubuntu-latest
    # `gp-furo-theme`'s build backend (`sphinx_vite_builder.build`) runs
    # `pnpm exec vite build` during editable installs, which the qa
    # runners can't satisfy (no pnpm/Node). qa's purpose is lint/types/
    # tests against Python sources — the rendered theme isn't exercised
    # here — so we set the documented escape-hatch env var on the whole
    # job. The backend then short-circuits and the install succeeds.
    # Test suites that build a Sphinx project with html_theme="gp-furo"
    # behave the same as they do on a stock checkout without vite —
    # Sphinx silently skips the missing static entries (no -W in qa).
    env:
      SPHINX_VITE_BUILDER_SKIP: "1"
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
    steps:
      - uses: actions/checkout@v6

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

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: Install workspace dependencies
        run: uv sync --all-packages --all-extras --group dev

      - name: Print Python versions
        run: |
          python -V
          uv run python -V
          uv run pytest --version

      - name: Lint with ruff check
        run: uv run ruff check .

      - name: Format with ruff format
        run: uv run ruff format . --check

      - name: Type check with mypy
        run: uv run mypy .

      - name: Validate package runtime versions
        if: matrix.python-version == '3.14'
        run: uv run python scripts/ci/package_tools.py check-versions

      - name: Test with pytest
        if: matrix.python-version != '3.14'
        run: uv run pytest

      - name: Test with pytest and coverage
        if: matrix.python-version == '3.14'
        run: uv run pytest --cov=./ --cov-report=xml

      - uses: codecov/codecov-action@v6
        if: matrix.python-version == '3.14'
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

  docs:
    runs-on: ubuntu-latest
    needs: qa
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.14
        uses: actions/setup-python@v6
        with:
          python-version: "3.14"

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      # `gp-furo-theme`'s build backend (`sphinx_vite_builder.build`)
      # runs vite during editable install, populating the gitignored
      # `static/` tree so the docs build below picks up real CSS / JS.
      # The pnpm/Node steps below give the backend a working toolchain.
      - name: Set up pnpm
        uses: pnpm/action-setup@v6
        with:
          version: 10

      - name: Set up Node
        uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: pnpm

      - name: Install workspace dependencies
        run: uv sync --all-packages --all-extras --group dev

      - name: Build documentation with warnings as errors
        run: uv run sphinx-build -W -b dirhtml docs docs/_build/html

  packages:
    runs-on: ubuntu-latest
    needs: qa
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.14
        uses: actions/setup-python@v6
        with:
          python-version: "3.14"

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      # `gp-furo-theme`'s sdist + wheel both go through
      # `sphinx_vite_builder.build`, which runs vite. The wheels
      # produced here are consumed by the smoke matrix below — they
      # MUST contain populated `static/`, otherwise downstream smoke
      # installs render unstyled. pnpm + Node satisfy that toolchain
      # requirement; the backend's wheel-from-sdist short-circuit
      # (no `web/` in unpacked sdist → assume pre-baked) means smoke
      # jobs themselves don't need this setup.
      - name: Set up pnpm
        uses: pnpm/action-setup@v6
        with:
          version: 10

      - name: Set up Node
        uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: pnpm

      - name: Install workspace dependencies
        run: uv sync --all-packages --all-extras --group dev

      - name: Validate package runtime versions
        run: uv run python scripts/ci/package_tools.py check-versions

      - name: Build all workspace packages
        run: uv build --all-packages --out-dir dist --clear

      - name: Validate distributions with twine
        run: uvx twine check dist/*

      - name: Upload package distributions
        uses: actions/upload-artifact@v7
        with:
          name: dist
          path: dist/

  smoke:
    runs-on: ubuntu-latest
    needs: packages
    strategy:
      fail-fast: false
      matrix:
        target:
          - root-install
          - gp-sphinx
          - sphinx-gp-theme
          - sphinx-fonts
          - sphinx-autodoc-argparse
          - sphinx-autodoc-docutils
          - sphinx-autodoc-sphinx
          - sphinx-autodoc-pytest-fixtures
          - sphinx-autodoc-api-style
          - sphinx-autodoc-fastmcp
          - sphinx-autodoc-typehints-gp
          - sphinx-ux-badges
          - sphinx-ux-autodoc-layout
          - sphinx-vite-builder
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.14
        uses: actions/setup-python@v6
        with:
          python-version: "3.14"

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: Download package distributions
        if: matrix.target != 'root-install'
        uses: actions/download-artifact@v8
        with:
          name: dist
          path: dist

      - name: Smoke test root bootstrap install
        if: matrix.target == 'root-install'
        # The root install transitively builds `gp-furo-theme`, which
        # routes through `sphinx_vite_builder.build`. The smoke target
        # only verifies that imports resolve — it doesn't exercise the
        # rendered theme — so we skip the vite invocation.
        env:
          SPHINX_VITE_BUILDER_SKIP: "1"
        run: python scripts/ci/package_tools.py smoke root-install

      - name: Smoke test built package artifact
        if: matrix.target != 'root-install'
        run: python scripts/ci/package_tools.py smoke "${{ matrix.target }}" --dist-dir dist