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

* docs(xarray): drop stray Returns section from conformance docstring

The conformance endpoint had a docstring `Returns:` section but no return
type annotation, which makes griffe emit a warning and fails `mkdocs build
--strict`. Match the sibling `landing` endpoint (summary-only docstring, no
annotation) so the strict docs build passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* ci: test docs build on PRs and rename workflow to docs.yml

Rename `deploy_mkdocs.yml` -> `docs.yml` and add a `test` job that runs
`mkdocs build --strict` on pull requests, so broken docs are caught before
they reach main. The existing deploy job is preserved and now gated behind
`needs: test` (push to main only).

Refs #1408

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: wakame1367

.github/workflows/deploy_mkdocs.yml

@@ -0,0 +1,90 @@
+name: Publish docs via GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      # Only rebuild/deploy the website when docs have changed
+      - 'README.md'
+      - 'CHANGES.md'
+      - 'CONTRIBUTING.md'
+      - 'deployment/**'
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      # Test the docs build whenever something that feeds the docs changes.
+      # The API reference and OpenAPI schema are generated from the source,
+      # so source/dependency changes can break the strict build too.
+      - 'README.md'
+      - 'CHANGES.md'
+      - 'CONTRIBUTING.md'
+      - 'deployment/**'
+      - 'docs/**'
+      - 'src/titiler/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test docs build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.9.*"
+          enable-cache: false
+
+      - name: Generate OpenAPI schema
+        run: |
+          uv run python -c'from titiler.application.main import app; import json; print(json.dumps(app.openapi(), indent=4))' > docs/src/endpoints/openapi.json
+
+      - name: Build docs (strict)
+        run: |
+          uv run --group docs mkdocs build --strict -f docs/mkdocs.yml
+
+  deploy:
+    name: Deploy docs
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: github-pages
+    permissions:
+      contents: write # mkdocs gh-deploy pushes the built site to gh-pages
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.9.*"
+          enable-cache: false
+
+      - name: Generate OpenAPI schema
+        run: |
+          uv run python -c'from titiler.application.main import app; import json; print(json.dumps(app.openapi(), indent=4))' > docs/src/endpoints/openapi.json
+
+      - name: Deploy docs
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          uv run --group docs mkdocs gh-deploy --force -f docs/mkdocs.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/docs.yml

@@ -432,9 +432,6 @@ def conformance(
 
     Called with `GET /conformance`.
 
-    Returns:
-        Conformance classes which the server conforms to.
-
     """
     data = {"conformsTo": sorted(TITILER_CONFORMS_TO)}