# .github/workflows/build-docs.yml
# See https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

name: Build Documentation

on:
  pull_request:
    paths:
      - "docs/**"
      - "src/**/*.py"
      - "noxfile.py"
      - "pyproject.toml"
      - ".github/workflows/build-docs.yml"
      - ".ruff.toml" # Affects docstrings via linting
      - "pyrightconfig.json" # Affects type hints in docs

  push:
    branches:
      - main
      - master
    paths:
      - "docs/**"
      - "src/**/*.py"
      - "noxfile.py"
      - "pyproject.toml"
      - ".github/workflows/build-docs.yml"

  workflow_dispatch:

jobs:
  build-docs:
    name: Run Documentation Build Check
    runs-on: ubuntu-latest

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

      - name: Install uv
        uses: astral-sh/setup-uv@v6

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version-file: ".github/workflows/.python-version"

      - name: Build documentation
        run: uvx nox -s build-docs

      - name: Upload documentation (HTML) Artifact
        uses: actions/upload-artifact@v4
        with:
          name: html-docs
          path: docs/_build/html/
