Combine stable and release docs workflows (#1570)

Currently, these workflows conflict because they both trigger off a tag
and try to push the 'gh-pages' branch. Whichever workflow finishes
second always fails. Here we change to push to both places from the
stable workflow but only push to the top level directory that the
release workflow was pushing when the tag appears to be the latest
release.

Closes #1554

Author: wshanks

.github/workflows/docs_release.yml

@@ -36,3 +36,16 @@ jobs:
         with:
           folder: docs/_build/html
           target-folder: stable/${{ env.version }}
+      - name: Check current tag is the latest
+        id: check-latest
+        run: |
+          python tools/check_latest_version.py
+        continue-on-error: true
+      - name: Deploy top level
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/_build/html/
+          clean-exclude: |
+            stable/*
+            dev/*
+        if: steps.check-latest.outcome == "success"

.github/workflows/docs_stable.yml

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+
+# This code is part of Qiskit Experiments.
+#
+# (C) Copyright IBM 2025.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Check that the highest git version tag on the repo matches the current version"""
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+version_pattern = re.compile(r"^\d+(\.\d+)*$")
+
+
+def _main():
+    """Return True if VERSION.txt matches a tag higher than any other version tag
+
+    NOTE: this function is primarily intended for the docs publishing automated
+    workflow. It retruns true even if the current commit is not tagged with the
+    latest version tag. It works this way so that a follow up commit can be
+    pushed to fix a possible error in the docs publishing workflow without
+    needing to tag again with a higher verison number just for the docs.
+    """
+    proc = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"], check=True, text=True, capture_output=True
+    )
+    repo_base = Path(proc.stdout.strip())
+
+    proc = subprocess.run(["git", "tag", "--list"], check=True, text=True, capture_output=True)
+    all_tags = [t.strip() for t in proc.stdout.splitlines()]
+    all_tags = [t for t in all_tags if version_pattern.match(t)]
+    highest_version = max(all_tags, key=lambda t: tuple(int(p) for p in t.split(".")))
+
+    version = (repo_base / "qiskit_experiments/VERSION.txt").read_text().strip()
+
+    if version != highest_version:
+        return False
+
+    return True
+
+
+if __name__ == "__main__":
+    if not _main():
+        sys.exit(1)