docs-build.yml

name: Docs Build (reusable)

# Heart-owned reusable Sphinx docs-build check for the PyAuto libraries.
# Each library's .github/workflows/docs.yml is a thin caller:
#
#   jobs:
#     docs:
#       uses: PyAutoLabs/PyAutoHeart/.github/workflows/docs-build.yml@main
#       with: { package: autolens }
#       secrets: inherit
#
# The workflow filename is intentionally stable for downstream callers.
#
# Why this exists: ReadTheDocs builds with fail_on_warning: false and nothing
# else builds the docs pre-merge, so broken API pages and stale autosummary
# entries rot silently (the RTD hygiene census, PyAutoFit#1341). This job
# builds the Sphinx HTML on PRs and fails when the warning count regresses
# past the repo's recorded baseline (docs/sphinx_warning_baseline.txt; a
# missing file means 0 — strict). Mirrors lib-tests.yml mechanics: dependency
# chain cloned from source at the matching branch when one exists.

on:
  workflow_call:
    inputs:
      package:
        description: "PyAuto package to build docs for: autoconf|autofit|autoarray|autogalaxy|autolens|pyautoscientist (docs-only)"
        required: true
        type: string

jobs:
  docs-build:
    runs-on: ubuntu-latest
    steps:
      - name: Map package → repo + dependency chain
        id: map
        run: |
          install=package
          case "${{ inputs.package }}" in
            autoconf)   repo=PyAutoConf;   deps="" ;;
            autofit)    repo=PyAutoFit;    deps="PyAutoConf" ;;
            autoarray)  repo=PyAutoArray;  deps="PyAutoConf" ;;
            autogalaxy) repo=PyAutoGalaxy; deps="PyAutoConf PyAutoFit PyAutoArray" ;;
            autolens)   repo=PyAutoLens;   deps="PyAutoConf PyAutoFit PyAutoArray PyAutoGalaxy" ;;
            # Docs-only repos: no pip package — install docs/requirements.txt.
            pyautoscientist) repo=PyAutoBrain; deps=""; install=requirements ;;
            *) echo "::error::unknown package '${{ inputs.package }}'"; exit 1 ;;
          esac
          echo "repo=$repo" >> "$GITHUB_OUTPUT"
          echo "deps=$deps" >> "$GITHUB_OUTPUT"
          echo "install=$install" >> "$GITHUB_OUTPUT"

      - name: Checkout ${{ steps.map.outputs.repo }} (repo under test, at the PR ref)
        uses: actions/checkout@v4
        with:
          path: ${{ steps.map.outputs.repo }}

      - name: Clone dependency libraries (matching branch if it exists)
        run: |
          set -e
          BRANCH="${{ github.head_ref || github.ref_name }}"
          for dep in ${{ steps.map.outputs.deps }}; do
            git clone "https://github.com/PyAutoLabs/$dep" "$dep"
            if git -C "$dep" ls-remote --exit-code --heads origin "$BRANCH" >/dev/null 2>&1; then
              echo "Branch $BRANCH exists in $dep — checking it out"
              git -C "$dep" checkout "$BRANCH"
            fi
          done

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip

      - name: Install (deps + package from source, [optional] + [docs] extras)
        run: |
          pip install --upgrade pip setuptools wheel
          if [ "${{ steps.map.outputs.install }}" = "requirements" ]; then
            pip install -r "./${{ steps.map.outputs.repo }}/docs/requirements.txt"
          else
            for r in ${{ steps.map.outputs.deps }}; do
              pip install "./$r[optional]"
            done
            pip install "./${{ steps.map.outputs.repo }}[optional,docs]"
          fi

      - name: Build docs (fail on warning-count regression)
        run: |
          cd "${{ steps.map.outputs.repo }}"
          python -m sphinx -b html docs docs/_build/html -w /tmp/sphinx-warnings.log
          count=$(wc -l < /tmp/sphinx-warnings.log)
          baseline=0
          if [ -f docs/sphinx_warning_baseline.txt ]; then
            baseline=$(tr -d '[:space:]' < docs/sphinx_warning_baseline.txt)
          fi
          echo "Sphinx warnings: $count (baseline: $baseline)"
          if [ "$count" -gt "$baseline" ]; then
            echo "::error::Sphinx warning count $count exceeds baseline $baseline — fix the new warnings (or, if they are pre-existing debt being surfaced, update docs/sphinx_warning_baseline.txt with justification)"
            cat /tmp/sphinx-warnings.log
            exit 1
          fi
          if [ "$count" -lt "$baseline" ]; then
            echo "::notice::Warning count $count is below baseline $baseline — consider ratcheting docs/sphinx_warning_baseline.txt down"
          fi