Rebuild the docs around tested examples; shrink README.v2.md to a pitch (#2978)

Author: maxisbey

.github/workflows/deploy-docs.yml

@@ -7,6 +7,9 @@ on:
       - v1.x
     paths:
       - docs/**
+      # docs pages include their code blocks from these files via `--8<--`, so a
+      # change here changes the rendered site even when no .md file moves.
+      - docs_src/**
       - mkdocs.yml
       - src/mcp/**
       - scripts/build-docs.sh

.github/workflows/shared.yml

@@ -110,3 +110,26 @@ jobs:
 
       - name: Check README snippets are up to date
         run: uv run --frozen scripts/update_readme_snippets.py --check --readme README.v2.md
+
+  # `mkdocs.yml` sets `strict: true` and `pymdownx.snippets: check_paths: true`,
+  # but until this job existed the docs were only ever built post-merge by
+  # `deploy-docs.yml`, so a broken link, a missing nav target, or a deleted
+  # `docs_src/` include went green on the PR and broke the next deploy of main.
+  # This is the check path; `deploy-docs.yml` stays the deploy path.
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+          version: 0.9.5
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --python 3.10
+
+      - name: Build the docs in strict mode
+        run: uv run --frozen --no-sync mkdocs build --strict

.pre-commit-config.yaml

@@ -65,5 +65,5 @@ repos:
         name: Check README snippets are up to date
         entry: uv run --frozen python scripts/update_readme_snippets.py --check
         language: system
-        files: ^(README\.v2\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
+        files: ^(README\.v2\.md|docs_src/.*\.py|examples/.*\.py|scripts/update_readme_snippets\.py)$
         pass_filenames: false