ci(docs): build the documentation on documentation-relevant pull requests

[ocots]

Why

Documentation.yml is the only job that executes the @example blocks and resolves the
@ref/@extref links, so it is the only check that can catch a broken page. It was reachable
solely through the run documentation label — and in practice the label was never applied:

PR	Section	Label	Docs build
#865 #866 #867 #868 #869	modelling · solve · results · flows · geometry	—	skipped
#871 #872 #873 #874	solve fixes · examples · getting started · migration	—	skipped

The twelve PRs of the v2.1 documentation rewrite merged without a single build. Building the site
locally on this branch shows what that let through — see "What the first build found" below.

What changes

1. The docs build runs on documentation-relevant pull requests. A paths filter on the
pull_request trigger covers everything the built site depends on:

• docs/** — the pages, make.jl, the doc environment
• src/** — the docstrings pulled into the generated API reference
• Project.toml — the compat bounds the doc environment resolves against
• .github/workflows/Documentation.yml — so a change to this file validates itself

The if: condition drops the label gate, since every event that now reaches the job is already
documentation-relevant. It keeps one guard: labeled fires once per label added, so reacting to
any label would re-run the job on every subsequent label.

2. docs/src/index.md gets Draft = false. make.jl sets draft = true globally and every
content page opts out individually — the landing page was the one that never did, so its five
@example blocks had never executed. With the meta in place the "Basic usage" block evaluates and
the landing page renders its figure. (Checked in the built output: solve(ocp) without
display=false does not dump the Ipopt log above the plot, which was the one risk worth
looking at.)

Trade-off, deliberately taken

A pull request touching none of the four paths above can no longer reach this job, not even with
the label. That is the intended consequence: such a PR cannot change what the site renders. The
label survives as a manual re-run handle on PRs that do match.

This widens CI slightly — src/** changes now build the docs where before they did not. That is
the point: a docstring-only change can break the generated API reference, and nothing else
catches it.

What the first build found

Built locally on this branch: 786 log lines, 12 errors, 186 warnings, zero failing @example
block, exit code 0. Three things worth recording, none of them fixed here:

1. solve/choosing-a-method.md publishes an UndefVarError. No ocp is defined anywhere on
   the page, and both try/catch blocks swallow it. The rendered page reads: "…so this raises
   AmbiguousDescription rather than silently picking one:" followed by
   UndefVarError(:ocp, 0x000000000000b0e3, Main). Same again eighty lines down, under
   "confirmed live".
2. flows/overview.md's "no integrator loaded" demo cannot fail. make.jl loads
   OrdinaryDiffEq at startup, so the try block succeeds and the page renders a fully
   constructed OptimalControlFlow where it promises an ExtensionError.
3. 166 unresolved @ref, all in docs/src/api/* — 45 in flows.md, 34 in types.md, 29 in
   problem.md, 15 in qualified.md. Zero in the hand-written guide pages. Root cause is at
   least partly that docs/inventories/ holds only ExaModels.toml and MadNLP.toml while
   make.jl references twelve inventories; the other ten fail to load and fall back to remote
   URLs, which is also what produces the two hard errors on api/internals.md.

Note on warnonly

makedocs runs with warnonly=true, so the build exits 0 despite all of the above. A green
check on this job does not yet mean the site is sound. Tightening warnonly is what turns this
into a real guard, but it has to wait until the 166 @ref backlog is cleared — doing it now would
leave CI permanently red. Deliberately untouched here.

Verification

This PR touches docs/src/index.md and the workflow file itself, so it triggers its own build.
Locally: julia --project=docs docs/make.jl exits 0, no @example block fails, and no tracked
file is modified by the build.