docs.yml

name: Docs

# Two gates over docs/handbuch/ — the section published into the Handbuch's
# "ChurchTools-Grundlagen" (#89):
#
# 1. `build` — mkdocs --strict, so a broken link or a page missing from the nav fails
#    the PR here rather than silently in the consuming site build.
# 2. `staleness` — reads each page's `sources:` globs and fails a PR that changes
#    documented code without re-signing the page.
#
# The staleness checker is vendored at .github/scripts/docs-staleness.mjs rather than
# called as the estate-wide reusable workflow: this repo is public and a public repo
# cannot call a reusable workflow out of a private one. It is a verified port of the
# canonical `App\Services\Docs\SourcesHasher` and reproduces the hashes that signer
# wrote, so pages stay signable from either side.
#
# Re-signing a page means recomputing `sources_hash` over its `sources:` — a sha256 over
# each resolved file's `<relative-path>\0<contents>\0`, sorted, truncated to 16 hex chars.
# Bumping `reviewed:` alone does NOT satisfy the gate; the point is that someone re-read
# the page against the new code.

on:
  push:
    branches: [main]
    paths:
      - "docs/handbuch/**"
      - "src/**"
      - ".github/workflows/docs.yml"
      - ".github/scripts/docs-staleness.mjs"
  pull_request:
    paths:
      - "docs/handbuch/**"
      - "src/**"
      - ".github/workflows/docs.yml"
      - ".github/scripts/docs-staleness.mjs"

# A newer push to the same PR supersedes the run in flight, so cancel it rather than
# let both occupy the org's concurrent-job slots. Pushes to main are never cancelled:
# every main commit keeps its own result. That needs a per-commit group for pushes —
# a shared group still holds only one pending run and cancels the older pending one
# when a third arrives, even with cancel-in-progress off.
concurrency:
  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install MkDocs
        run: pip install -r docs/handbuch/requirements.txt
      - name: Build the section (strict)
        run: mkdocs build -f docs/handbuch/mkdocs.yml --strict

  # `src/**` changed without the matching page re-signed → this fails. Signing is the
  # acknowledgement, not the file appearing in the diff.
  staleness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Check that documented sources are re-signed
        run: node .github/scripts/docs-staleness.mjs