name: Documentation

on:
  push:
    branches: [ main ]
    paths:
      - 'docs/**'
      - 'README.md'
      - '**/*.rst'
      - '.github/workflows/docs.yml'
  pull_request:
    branches: [ main ]
    paths:
      - 'docs/**'
      - 'README.md'
      - '**/*.rst'

permissions:
  contents: read

jobs:
  docs:
    name: Build Documentation
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v6

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

    - name: Cache pip dependencies
      uses: actions/cache@v6
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-docs-${{ hashFiles('**/pyproject.toml') }}
        restore-keys: |
          ${{ runner.os }}-pip-docs-

    - name: Install docs dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -e ".[docs]"

    - name: Build Sphinx documentation
      run: |
        cd docs
        make clean
        make html SPHINXOPTS="-W --keep-going" || {
          echo "::error::Sphinx build failed with warnings"
          exit 1
        }

    - name: Check for broken links
      run: |
        cd docs
        make linkcheck || {
          echo "::warning::Some links are broken (non-blocking)"
          exit 0
        }

    - name: Upload docs artifact
      if: github.ref == 'refs/heads/main'
      uses: actions/upload-pages-artifact@v5
      with:
        path: docs/_build/html

  deploy:
    name: Deploy to GitHub Pages
    needs: docs
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v5