From 70d3eed812eb6e078744519131b29a1f9954946a Mon Sep 17 00:00:00 2001
From: Romeo Kienzler <romeo.kienzler1@ibm.com>
Date: Tue, 30 Jun 2026 13:47:05 +0200
Subject: [PATCH] ci: add docs build check on PRs and consolidate PyPI
 publishing

Two release-process hardening changes:

1. Add docs-check.yml: runs 'mkdocs build --strict' on pull requests
   that touch docs/mkdocs/sources, so broken mkdocstrings references
   (like the benchmark -> terratorch_iterate rename) and dead nav links
   are caught on the PR instead of during a release deploy.

2. Consolidate the two PyPI-publish workflows into one. Previously both
   publish-pypi.yml (on tag) and python-publish.yml (on release) fired
   for every release and raced to upload the same artifacts, with the
   loser logging a 400. Keep the more robust tag-based workflow (twine
   check, setuptools_scm, full history), add --skip-existing so moving a
   tag to pick up a fix no longer fails, and delete python-publish.yml.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Romeo Kienzler <romeo.kienzler1@ibm.com>
---
 .github/workflows/docs-check.yml     | 48 ++++++++++++++++++++++++++++
 .github/workflows/publish-pypi.yml   |  4 ++-
 .github/workflows/python-publish.yml | 39 ----------------------
 3 files changed, 51 insertions(+), 40 deletions(-)
 create mode 100644 .github/workflows/docs-check.yml
 delete mode 100644 .github/workflows/python-publish.yml

diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml
new file mode 100644
index 00000000..6160fd59
--- /dev/null
+++ b/.github/workflows/docs-check.yml
@@ -0,0 +1,48 @@
+name: Check Docs Build
+
+# Builds the documentation on pull requests so broken mkdocstrings
+# references, dead nav links, and other docs errors are caught before
+# merge instead of during a release deploy.
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'src/**'
+      - 'terratorch_iterate/**'
+      - '.github/workflows/docs-check.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: pip
+
+      - name: Install doc dependencies
+        run: |
+          pip install \
+            mkdocs-material \
+            mkdocstrings[python] \
+            mkdocs-git-revision-date-localized-plugin \
+            griffe
+
+      - name: Install claimed package (for mkdocstrings introspection)
+        run: pip install -e .
+
+      - name: Build docs (strict)
+        run: mkdocs build --strict
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
index 935daa9a..f7abe41a 100644
--- a/.github/workflows/publish-pypi.yml
+++ b/.github/workflows/publish-pypi.yml
@@ -34,4 +34,6 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
         run: |
           python -m twine check dist/*
-          python -m twine upload dist/* --non-interactive
+          # --skip-existing so re-triggered tag pushes (e.g. moving a tag to
+          # pick up a docs fix) don't fail when the version is already on PyPI.
+          python -m twine upload dist/* --non-interactive --skip-existing
diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml
deleted file mode 100644
index bdaab28a..00000000
--- a/.github/workflows/python-publish.yml
+++ /dev/null
@@ -1,39 +0,0 @@
-# This workflow will upload a Python Package using Twine when a release is created
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
-
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-
-name: Upload Python Package
-
-on:
-  release:
-    types: [published]
-
-permissions:
-  contents: read
-
-jobs:
-  deploy:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python
-      uses: actions/setup-python@v3
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install build
-    - name: Build package
-      run: python -m build
-    - name: Publish package
-      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
-      with:
-        user: __token__
-        password: ${{ secrets.PYPI_API_TOKEN }}