docs.yml

name: Docs

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

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

jobs:
  docs:
    name: Check docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
      - name: Install just
        uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
        with:
          repo: casey/just
          version: 1.58.0
      # Fast source-level guards that need no built site, so they run before the (slower)
      # build for a quick failure: every public export is in the API reference, and no
      # docstring/Markdown carries reStructuredText markup that MkDocs won't render.
      - run: just check-doc-exports
      - run: just lint-docs
      # --strict turns warnings into errors, so a docs code block that fails to execute
      # at build time (e.g. a non-exec python fence disrupting a later exec="true" block)
      # fails CI instead of merging as a silent warning.
      - run: just docs-build
        env:
          DISABLE_MKDOCS_2_WARNING: "true"
          NO_MKDOCS_2_WARNING: "true"
      - run: just check-doc-links
        continue-on-error: true