docs.yml

# SPDX-FileCopyrightText: 2026 bartzbeielstein
#
# SPDX-License-Identifier: GPL-2.0-or-later
#
# =============================================================================
# .github/workflows/docs.yml  —  Documentation Build & Deploy
# =============================================================================
# Pipeline:
#   1. Checkout
#   2. Set up Python + uv
#   3. Install Python dependencies
#   4. Install Quarto CLI (PINNED)
#   5. Generate API reference with quartodoc
#   6. Render Quarto site & publish to rh-pages
# =============================================================================

name: Documentation

on:
  push:
    branches:
      - main
      - develop
    paths:
      - '**/*.qmd'
      - '_quarto.yml'
      - 'src/spotdesirability/**'
      - 'pyproject.toml'
  workflow_dispatch:

permissions: read-all

env:
  # ⚠️ Pinned to match production safety standards.
  QUARTO_VERSION: "1.8.27"
  PYTHON_VERSION: "3.13"

jobs:
  deploy-docs:
    name: Build & Deploy Documentation
    runs-on: ubuntu-latest
    permissions:
      contents: write   # push access via gh-pages

    steps:
      - name: Checkout (full history)
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2
        with:
          fetch-depth: 0   # Full history ensures cross-referencing interlinks work safely

      - name: Set up Python ${{ env.PYTHON_VERSION }}
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v5.3.0
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Set up uv
        uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5.2.2

      - name: Install Python dependencies
        run: |
          # Use pyproject.toml [dev] dependencies to install quartodoc safely
          uv sync --group dev

      - name: Install Quarto CLI ${{ env.QUARTO_VERSION }}
        uses: quarto-dev/quarto-actions/setup@8a96df13519ee81fd526f2dfca5962811136661b # v2.1.2
        with:
          version: ${{ env.QUARTO_VERSION }}

      - name: Verify Quarto installation
        run: quarto check

      - name: Generate API reference with quartodoc
        # Rebuild dynamically instead of keeping autogenerated `.qmd` tracked into git
        run: |
          uv run python docs/quartodoc_build.py
          uv run quartodoc interlinks



      - name: Render Quarto site
        run: uv run quarto render --no-cache

      - name: Deploy to GitHub Pages
        uses: quarto-dev/quarto-actions/publish@8a96df13519ee81fd526f2dfca5962811136661b # v2.1.2
        with:
          target: gh-pages
          path: _site
          render: "false"   # Handled in prior step
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}