docs.yml

# Documentation validation.
#
# Builds the modernized docs (docs_src/build.py: Markdown -> HTML + man + PDF)
# and runs the validators that lock in the reverse-DocBook migration's
# guarantees. Modeled on ci.yml/fuzz.yml conventions: hard gates block PRs,
# advisory tiers are continue-on-error, and heavy work (PDF/TeX-free but slow,
# external link check) is scheduled-only or best-effort so per-PR jobs stay
# fast.
#
# Tooling comes from the flake dev shell (nix develop) so CI matches local
# exactly -- pandoc, weasyprint, poppler-utils, mandoc, codespell, lychee and
# write-good are all pinned there.
#
# HARD gates (fail the PR):     build (HTML+man), completeness, spelling,
#                               internal link-check, man-lint.
# ADVISORY (continue-on-error): prose (write-good), external link-check.
# BEST-EFFORT (scheduled / continue-on-error): PDF build + validation (slow).

name: Docs

on:
  push:
    branches: [master]
  pull_request:
    paths:
      - 'docs_src/**'
      - '.github/workflows/docs.yml'
      - 'flake.nix'
      - 'dist/RELEASE'
  workflow_dispatch:
  schedule:
    # Weekly (Mon 05:23 UTC): the full run including the slow PDF build and the
    # external link check, which are best-effort/skipped on per-PR runs.
    - cron: '23 5 * * 1'

concurrency:
  group: docs-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  # ----------------------------------------------------------------------------
  # Build HTML + man (fast, always) and run the hard gates that depend on the
  # generated output. PDF is built here only on schedule/dispatch (see the
  # `pdf` job) so a PR isn't gated on the ~4-minute weasyprint pass.
  # ----------------------------------------------------------------------------
  build:
    name: build + gates (html, man, completeness, spelling, links, man-lint)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Nix (flakes enabled)
        uses: cachix/install-nix-action@v27
        with:
          extra_nix_config: |
            experimental-features = nix-command flakes

      # 1. BUILD (hard): HTML + man with 0 errors. --no-pdf keeps the PR fast;
      #    the PDF path is exercised by the `pdf` job (scheduled/best-effort).
      - name: Build HTML + man
        run: nix develop --command bash -c 'cd docs_src && python3 build.py --no-pdf'

      # build.py self-check guards the md->man reshape, PDF book discovery, and
      # the .md->.html link rewrite (unit-level, no external tools).
      - name: build.py self-check
        run: nix develop --command bash -c 'cd docs_src && python3 build.py --selfcheck'

      # 2. (RETIRED) The no-loss gate compared the OLD scraped-DocBook docs/
      #    tree against docs_src/ to prove the reverse migration dropped
      #    nothing. It did its job (PRs #119/#120, ~100% retention) and the
      #    docs/ source has since been removed from master (it lives on the
      #    gh-pages historical archive). With no source tree to diff against
      #    the gate can't run, so it is retired. verify_all.py/verify.py stay
      #    in docs_src/_migrate/ for reference against that archive.

      # 3. COMPLETENESS GATE (hard): every public db.h function is documented
      #    (28/28), and every uncovered method is on the frozen allowlist -- a
      #    NEW undocumented API fails.
      - name: Completeness gate (API coverage)
        run: nix develop --command bash -c 'python3 docs_src/_migrate/man_coverage.py --ci'

      # 4. SPELLING (hard on NEW typos): codespell, baselined against the legacy
      #    typo backlog so only newly-introduced typos fail.
      - name: Spelling gate (codespell, baselined)
        run: nix develop --command bash -c 'python3 docs_src/_migrate/spellcheck.py'

      # 6. INTERNAL LINK CHECK (hard): every link into migrated content must
      #    resolve. Deferred-tree + un-migrated-asset links are excluded (see
      #    docs_src/_migrate/lychee.toml). External links are the advisory job.
      - name: Internal link check (lychee, offline)
        run: |
          nix develop --command bash -c \
            'shopt -s globstar; lychee --offline --config docs_src/_migrate/lychee.toml --no-progress "docs-build/html/**/*.html"'

      # 7. MAN-LINT (hard): 0 ERRORS from mandoc across every generated .3
      #    (STYLE/WARNING are fine).
      - name: Man-lint (mandoc -Tlint, 0 ERRORS)
        run: |
          nix develop --command bash -c '
            e=0
            for f in docs-build/man/man3/*.3; do
              if mandoc -Tlint "$f" 2>&1 | grep -q "ERROR"; then
                echo "ERRORS in $f:"; mandoc -Tlint "$f" 2>&1 | grep "ERROR" | head -3
                e=$((e+1))
              fi
            done
            echo "man pages with ERRORs: $e"
            test "$e" -eq 0'

  # ----------------------------------------------------------------------------
  # 5. PROSE (advisory): write-good passive-voice / wordiness counts. This is
  # decades-old technical prose -- surface the numbers, never gate.
  # ----------------------------------------------------------------------------
  prose:
    name: prose advisory (write-good)
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - uses: actions/checkout@v4
      - name: Install Nix (flakes enabled)
        uses: cachix/install-nix-action@v27
        with:
          extra_nix_config: |
            experimental-features = nix-command flakes
      - name: write-good suggestion counts (per tree)
        run: |
          nix develop --command bash -c '
            shopt -s globstar
            total=0
            for d in docs_src/api/* docs_src/guides/*; do
              [ -d "$d" ] || continue
              n=$(write-good "$d"/**/*.md 2>/dev/null | grep -c "on line" || true)
              printf "%-40s %5s suggestions\n" "$d" "$n"
              total=$((total+n))
            done
            echo "::notice title=Prose (write-good)::$total advisory suggestion(s) across docs_src"'

  # ----------------------------------------------------------------------------
  # PDF (best-effort / scheduled): weasyprint renders one PDF per book (~4 min
  # over all 13). Not a per-PR gate -- runs on schedule/dispatch, or on a PR
  # that touches build.py's PDF path. continue-on-error so a rendering hiccup
  # informs without blocking.
  # ----------------------------------------------------------------------------
  pdf:
    name: pdf build + validate (best-effort)
    runs-on: ubuntu-latest
    continue-on-error: true
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || github.event_name == 'push'
    steps:
      - uses: actions/checkout@v4
      - name: Install Nix (flakes enabled)
        uses: cachix/install-nix-action@v27
        with:
          extra_nix_config: |
            experimental-features = nix-command flakes
      - name: Build all outputs (incl. PDF)
        run: nix develop --command bash -c 'cd docs_src && timeout 900 python3 build.py'
      - name: Validate PDFs (non-empty, page count, title-page version)
        run: nix develop --command bash -c 'python3 docs_src/_migrate/validate_pdf.py'
      - name: Upload PDFs
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: docs-pdf
          path: docs-build/pdf/*.pdf
          if-no-files-found: ignore

  # ----------------------------------------------------------------------------
  # External link check (advisory / scheduled): lychee WITH network, so it
  # depends on the reachability of third-party sites. Never gates; scheduled
  # and dispatch only so PRs don't wait on the network.
  # ----------------------------------------------------------------------------
  external-links:
    name: external link check (advisory)
    runs-on: ubuntu-latest
    continue-on-error: true
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
    steps:
      - uses: actions/checkout@v4
      - name: Install Nix (flakes enabled)
        uses: cachix/install-nix-action@v27
        with:
          extra_nix_config: |
            experimental-features = nix-command flakes
      - name: Build HTML
        run: nix develop --command bash -c 'cd docs_src && python3 build.py --no-pdf'
      - name: Check external links (network, advisory)
        run: |
          nix develop --command bash -c '
            shopt -s globstar
            lychee --no-progress --scheme http --scheme https \
              --exclude "localhost" --max-concurrency 8 \
              "docs-build/html/**/*.html" || true'

  # ----------------------------------------------------------------------------
  # Publish (manual): regenerate HTML + PDF + man and push them to the gh-pages
  # branch under /reference/ (Pages is legacy branch-based, served from
  # gh-pages:/). workflow_dispatch only -- publishing is a deliberate act, not
  # something every push should do. The landing page (gh-pages:/index.html) and
  # the historical archive (gh-pages:/docs/) are left untouched.
  # ----------------------------------------------------------------------------
  publish:
    name: publish to gh-pages (manual)
    runs-on: ubuntu-latest
    if: github.event_name == 'workflow_dispatch'
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - name: Install Nix (flakes enabled)
        uses: cachix/install-nix-action@v27
        with:
          extra_nix_config: |
            experimental-features = nix-command flakes
      - name: Build the full site (HTML + PDF + man)
        run: nix develop --command bash -c 'cd docs_src && python3 build.py'
      - name: Deploy /reference/ to gh-pages
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          ver=$(sed -n 's/^DB_VERSION_PATCH=//p' dist/RELEASE)
          full="5.3.$ver"
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          tar czf "/tmp/libdb-man-$full.tar.gz" -C docs-build/man man3
          git fetch origin gh-pages
          git worktree add /tmp/ghp origin/gh-pages
          rm -rf /tmp/ghp/reference
          mkdir -p /tmp/ghp/reference/pdf
          cp -r docs-build/html/* /tmp/ghp/reference/
          cp docs-build/pdf/*.pdf /tmp/ghp/reference/pdf/
          cp "/tmp/libdb-man-$full.tar.gz" "/tmp/ghp/reference/libdb-man-$full.tar.gz"
          ( cd /tmp/ghp && git add -A && \
            git commit -m "Publish documentation reference ($full) [ci]" && \
            git push origin HEAD:gh-pages )