docs.yml

name: Docs

on:
  pull_request:
    branches: [main]
    paths:
      - "docs/**"
      - "mkdocs.yml"
      - "pyproject.toml"
      - "src/**"
      - ".github/workflows/docs.yml"
  push:
    branches: [main]
    paths:
      - "docs/**"
      - "mkdocs.yml"
      - "pyproject.toml"
      - "src/**"
      - ".github/workflows/docs.yml"

# Least-privilege: read code for the build; ``deployments: write`` lets
# the Cloudflare Pages action attach a deployment status to the commit.
permissions:
  contents: read
  deployments: write

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

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
        with:
          # mkdocstrings imports the package source; the spec submodule
          # is not referenced by docs but keep the conventional recursive
          # checkout consistent with ``ci.yml``.
          submodules: recursive

      - name: Install uv
        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
        with:
          enable-cache: true

      - name: Sync deps (docs group)
        # ``--group docs`` installs the project itself in editable mode
        # plus the ``docs`` dependency group. mkdocstrings needs to
        # import ``openarmature`` to introspect docstrings, which the
        # editable install provides.
        run: uv sync --frozen --group docs

      - name: Build site (strict)
        # ``--strict`` fails the build on any warning. Catches broken
        # internal links, missing nav references, plugin misconfig
        # early — before the deploy step.
        run: uv run mkdocs build --strict

      - name: Deploy to Cloudflare Pages
        # Only deploy on pushes to main. PR builds prove the site
        # builds but do not deploy.
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0  # v4.0.0
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          # Pass an ASCII-safe commit message to Cloudflare. The
          # deployment API rejects some valid-UTF-8 characters (e.g.
          # the section sign and arrow glyphs commonly used in spec
          # references), and the failure surfaces only at deploy time.
          # The SHA is sufficient to cross-reference the GitHub commit.
          command: pages deploy site --project-name=openarmature-python-docs --branch=main --commit-hash=${{ github.sha }} --commit-message="docs deploy ${{ github.sha }}"