From 552c675d967f41eedfcbba639c1bed52d8d8c9b3 Mon Sep 17 00:00:00 2001 From: Kota Yuhara Date: Sat, 25 Jul 2026 15:03:01 +0900 Subject: [PATCH 1/2] 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 --- src/titiler/xarray/titiler/xarray/main.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/titiler/xarray/titiler/xarray/main.py b/src/titiler/xarray/titiler/xarray/main.py index 7baa46246..89e3313bc 100644 --- a/src/titiler/xarray/titiler/xarray/main.py +++ b/src/titiler/xarray/titiler/xarray/main.py @@ -432,9 +432,6 @@ def conformance( Called with `GET /conformance`. - Returns: - Conformance classes which the server conforms to. - """ data = {"conformsTo": sorted(TITILER_CONFORMS_TO)} From 01d669db0c57f5cfeb061df3bc447eed2686fc0c Mon Sep 17 00:00:00 2001 From: Kota Yuhara Date: Sat, 25 Jul 2026 15:03:01 +0900 Subject: [PATCH 2/2] 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 --- .github/workflows/deploy_mkdocs.yml | 46 --------------- .github/workflows/docs.yml | 90 +++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+), 46 deletions(-) delete mode 100644 .github/workflows/deploy_mkdocs.yml create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/deploy_mkdocs.yml b/.github/workflows/deploy_mkdocs.yml deleted file mode 100644 index 597c41006..000000000 --- a/.github/workflows/deploy_mkdocs.yml +++ /dev/null @@ -1,46 +0,0 @@ -name: Publish docs via GitHub Pages - -on: - push: - branches: - - main - paths: - # Only rebuild website when docs have changed - - 'README.md' - - 'CHANGES.md' - - 'CONTRIBUTING.md' - - 'deployment/**' - - 'docs/**' - - '.github/workflows/deploy_mkdocs.yml' - -jobs: - build: - name: Deploy docs - 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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - with: - persist-credentials: false - - - name: Install uv - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2 - 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 }} diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..098c96449 --- /dev/null +++ b/.github/workflows/docs.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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + persist-credentials: false + + - name: Install uv + uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2 + 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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + persist-credentials: false + + - name: Install uv + uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2 + 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 }}