docs.yml

name: Docs

# Publishes one GitHub Pages site containing both the engineering documentation
# and the API reference:
#
#   /       MkDocs Material site built from docs/
#   /api/   Swagger UI rendering the OpenAPI spec generated by the build
#
# The two are a single static artifact and a single deploy.
#
# This job needs Docker: the OpenAPI spec is generated by an integration test
# running against a Testcontainers PostgreSQL. A hosted static-site builder
# without Docker could still build the MkDocs pages, but the spec would be
# missing and the API reference would fail at runtime -- silently, since it is
# fetched client-side. GitHub's runner provides Docker, so the whole site is
# built in one place.

on:
  push:
    branches: [master]
    # Only rebuild when something that affects the site changes. The API
    # reference depends on the Java sources because the OpenAPI spec is
    # generated from the running application.
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'requirements-docs.txt'
      - 'src/main/java/**'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

# Never run two deploys at once, and do not cancel one in progress -- a
# half-finished Pages deploy is a broken site.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    name: Build site
    runs-on: ubuntu-latest
    timeout-minutes: 25

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: temurin
          cache: maven

      # The spec is written by OpenApiSpecExportIT, which asserts the document
      # is complete before writing it. Generating it from the running
      # application is the only way to be certain the published reference
      # matches the code -- a hand-maintained spec drifts.
      - name: Generate the OpenAPI spec
        run: ./mvnw -B --no-transfer-progress verify

      - name: Stage the spec for the site
        run: |
          set -euo pipefail
          test -s target/openapi.json || { echo "openapi.json was not generated"; exit 1; }
          mkdir -p docs/api
          cp target/openapi.json docs/api/openapi.json
          echo "Spec staged: $(python3 -c 'import json;print(len(json.load(open("docs/api/openapi.json"))["paths"]),"paths")')"

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: pip
          cache-dependency-path: requirements-docs.txt

      - name: Install MkDocs
        run: pip install -r requirements-docs.txt

      # --strict turns broken internal links and missing nav targets into build
      # failures. A portfolio docs site with dead links is worse than none.
      - name: Build site
        run: mkdocs build --strict

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: site

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4