ci: test docs build on PRs (strict) and rename to docs.yml

[wakame1367]

Part of #1408 (aligning the workflows with the stac-auth-proxy layout), opened as a draft while the overall scope is confirmed in the issue.

What

Today the docs are only built when they are deployed on push to main (deploy_mkdocs.yml), so a PR that breaks the documentation build is only discovered after it is merged. This adds a docs build check on pull requests.

• rename deploy_mkdocs.yml → docs.yml;
• add a test job that runs mkdocs build --strict on pull_request (path-filtered to inputs that feed the docs: docs/**, README.md, CHANGES.md, CONTRIBUTING.md, deployment/**, src/titiler/**, pyproject.toml, uv.lock, and the workflow itself);
• keep the existing deploy job unchanged, now gated behind needs: test and if: github.event_name == 'push' && github.ref == 'refs/heads/main' — so deploy still only runs on push to main.

Prerequisite fix

mkdocs build --strict currently fails on main with a single griffe warning:

griffe: src/titiler/xarray/titiler/xarray/main.py:436: No type or annotation for returned value

The conformance endpoint has a docstring Returns: section but no return-type annotation. The first commit drops that section, which makes the strict build pass.

I went with removing the section rather than adding an annotation because that's what matches the existing conventions:

• titiler/xarray/main.py is the only main.py with an API reference page in docs/mkdocs.yml (api/titiler/xarray/main.md), which is why only this one is scanned by griffe — the identical conformance in titiler/application/main.py isn't affected;
• conformance was the only function in that file carrying a Returns: section — its sibling landing, which returns the same HTML-or-JSON union, has a summary-only docstring;
• no endpoint in the codebase that can return either create_html_response(...) or a dict carries a return annotation, and annotating it would mean naming starlette's private _TemplateResponse in a union.

Happy to add a return-type annotation instead if you'd rather have the type than the prose.

Notes / scoping

• I intentionally did not change the deploy trigger paths, so the deploy cadence is unchanged; only the PR test uses the broader path set.
• zizmor --min-severity medium (the repo's pre-commit gate) passes on docs.yml. Pedantic reports one low concurrency-limits note, which I left off to stay consistent with the existing ci.yml / previous deploy_mkdocs.yml (also no concurrency block) and to avoid cancelling an in-flight gh-pages deploy.

Verified locally: mkdocs build --strict -f docs/mkdocs.yml succeeds after the docstring fix, and pre-commit run (ruff/mypy/zizmor) passes on the changed files.

🤖 Generated with Claude Code

[wakame1367]

Note on the red benchmark job: it fails with Resource not accessible by integration in the "Check and Store benchmark result" step. This is the standard fork-PR limitation — GITHUB_TOKEN is read-only for pull requests from a fork, so github-action-benchmark can't write its commit comment. It's unrelated to this change (benchmark passes on main; only touched files here are docs.yml and one docstring line). All other checks — Test docs build, tests 3.11–3.14, zizmor, lint — pass.

[wakame1367]

Correction to my earlier note — I was imprecise about the mechanism, and the details actually matter here.

The benchmark job didn't fail simply because this is a fork PR (my earlier #1448 was also from a fork and its benchmark passed). What actually happened:

1. a performance alert fired — WGS1984Quad longest_transaction went 0.03s → 0.04s, ratio 1.33, just over the 130% threshold;
2. comment-on-alert: true then tried to POST a PR comment;
3. that write isn't permitted for a fork PR, so the step threw Resource not accessible by integration and the job failed even though fail-on-alert: false is set.

So this is still unrelated to the change (a docs-only diff can't affect runtime; 0.03 → 0.04s is timing noise at that granularity), but it also looks like a genuine workflow issue: on fork PRs an alert hard-fails the job, which contradicts the intent of fail-on-alert: false. I've opened a small separate PR for that so it doesn't clutter this one.