docs: Fix version warning banner (#1088)

There is a bug in documentation when releasing a new version X.Y.Z with
Z `>0`.
It shows the warning banner indicating that it's a development version,
even if it's really a release version.

It is because, to know if the banner must be showed, the release version
X.Y.Z is currently compared to the previous X.Y, instead of X.Y.Z. When
Z is `>0`, X.Y.Z is always greater than X.Y, so sphinx consider it's a
unstable version.

> If the version compares greater than the preferred version (or if the
version match contains the strings “dev”, “rc” or “pre”), the
announcement will say they are viewing an unstable development version
instead.


https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/announcements.html

---

This PR intends to compare current strict release with the previous
strict release to know if the banner must be showed, instead of the
MAJOR.MINOR.

Closes #1058.

.github/workflows/sphinx.yml

@@ -146,22 +146,34 @@ jobs:
             import json
 
             url = os.environ["URL"]
-            current = os.environ["CURRENT"]
+            version = os.environ["SPHINX_VERSION"]
+            release = os.environ["SPHINX_RELEASE"]
 
+            # Retrieve history
             response = requests.get(f"{url}/versions.json")
             response.raise_for_status()
 
-            history = set(map(operator.itemgetter("version"), response.json())) - {"dev"} | {current}
-            history = sorted(history, key=lambda x: float(x), reverse=True)[:10]
+            history = {version["name"]: version["version"] for version in response.json()}
 
+            # Add new version to history
+            history[version] = release
+
+            # Sort history, and always keep "dev" at the beginning
+            history = sorted(
+                history.items(),
+                key=lambda item: float(item[0]) if item[0] != "dev" else float('inf'),
+                reverse=True
+            )
+
+            # Rewrite the history with "dev" and the 10 latest versions
             new = [
                 {
                     "name": version,
-                    "version": version,
+                    "version": release,
                     "url": f"{url}/{version}/",
                     "preferred": i == 1,
                 }
-                for i, version in enumerate(["dev"] + history)
+                for i, (version, release) in enumerate(history[:11])
             ]
 
             os.mkdir("artifacts")
@@ -179,7 +191,8 @@ jobs:
               )
         env:
           URL: ${{ vars.DOCUMENTATION_URL }}
-          CURRENT: ${{ needs.sphinx-version.outputs.SPHINX_VERSION }}
+          SPHINX_VERSION: ${{ needs.sphinx-version.outputs.SPHINX_VERSION }}
+          SPHINX_RELEASE: ${{ needs.sphinx-version.outputs.SPHINX_RELEASE }}
       - uses: ./.github/actions/sphinx/deploy
         with:
           CONFIGURATION: ${{ secrets.RCLONE_CONFIG_DOCS }}

sphinx/conf.py

@@ -156,7 +156,7 @@
     ],
     "switcher": {
         "json_url": "https://skore.probabl.ai/versions.json",
-        "version_match": version,
+        "version_match": release,
     },
     "check_switcher": True,
     "show_version_warning_banner": True,