docs: reduce version selector entries and add archive page (Fixes #1395)

.github/workflows/docs.yml

@@ -31,33 +31,48 @@ jobs:
           git config --global user.email "github-actions[bot]@users.noreply.github.com"
 
       - name: Fetch gh-pages branch (if exists)
-        run: git fetch origin gh-pages:gh-pages || echo "gh-pages does not exist yet"
-
-      - name: Deploy documentation
-        run: |
-          if [[ "${GITHUB_REF}" == refs/heads/master ]]; then
-            echo "→ Deploying latest"
-            mike deploy latest --push --update-aliases
-            mike set-default latest --push
-          elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-            VERSION="${GITHUB_REF#refs/tags/}"
-            echo "→ Deploying version $VERSION"
-            mike deploy "$VERSION" --push --update-aliases
-            mike set-default --push stable
+        run: git fetch origin gh-pages:gh-pages || echo "gh-pages does not exist yet" 
+
+      - name: Extract versions.json
+        run: |
+          if git show origin/gh-pages:versions.json > versions.json 2>/dev/null; then
+            echo "Extracted versions.json from gh-pages"
+          else
+            echo '{"versions": []}' > versions.json
+            echo "Created empty versions.json because gh-pages does not exist yet"
           fi
 
-      - name: Copy and commit CNAME file (if exists)
-        run: |
-          git checkout gh-pages
-          if git checkout master -- docs/CNAME 2>/dev/null; then
-            mv docs/CNAME .
-            git add CNAME
-            if ! git diff --cached --quiet; then
-              git commit -m "Update CNAME file"
-              git push origin gh-pages
-            else
-              echo "No changes to commit for CNAME"
-            fi
+      - name: Filter versions
+        run: |
+          python scripts/filter_versions.py versions.json > version_filter_output.json
+
+      - name: Deploy version from tag (if tag triggered)
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          version="v${GITHUB_REF#refs/tags/}"
+          echo "Deploying version from tag: $version"
+          mike deploy --push "$version"
+
+      - name: Deploy visible versions
+        run: |
+          for v in $(jq -r '.visible[]' version_filter_output.json); do
+            mike deploy --push $v
+          done
+
+      - name: Deploy hidden versions
+        run: |
+          for v in $(jq -r '.hidden[]' version_filter_output.json); do
+            mike deploy --push --hidden $v
+          done
+
+      - name: Set default version
+        run: |
+          latest=$(jq -r '.visible[0]' version_filter_output.json)
+          if [ "$latest" = "null" ] || [ -z "$latest" ]; then
+            echo "No visible versions found — skipping set-default"
           else
-            echo "No CNAME file found in master branch"
+            mike set-default --push "$latest"
           fi
+
+
+

docs/archive.md

@@ -0,0 +1,5 @@
+# Version Archive
+
+This page lists all TM1py documentation versions.
+
+Older versions are accessible here even if they’re hidden from the version selector.

mkdocs.yml

@@ -21,6 +21,7 @@ nav:
   - How to Contribute: how-to-contribute.md
   - Links: links.md
   - API Reference: reference/
+  - Archive: archive.md
 
 exclude_docs: |
   README.md

scripts/filter_versions.py

@@ -0,0 +1,79 @@
+import json
+import re
+import sys
+from packaging.version import Version
+
+def parse_version(v):
+    """Convert 'v2.1.3' → Version('2.1.3')"""
+    return Version(v.lstrip("v"))
+
+def load_versions(path):
+    with open(path, "r") as f:
+        data = json.load(f)
+    return [entry["version"] for entry in data["versions"]]
+
+def group_versions(versions):
+    parsed = [parse_version(v) for v in versions]
+    parsed.sort(reverse=True)
+
+    # Group by major.minor
+    groups = {}
+    for v in parsed:
+        key = f"{v.major}.{v.minor}"
+        groups.setdefault(key, []).append(v)
+
+    return parsed, groups
+
+def select_visible(parsed, groups):
+    visible = []
+
+    # 1. Previous major version (e.g., v2.x if current is v3.x)
+    current_major = parsed[0].major
+    previous_major = current_major - 1
+
+    for v in parsed:
+        if v.major == previous_major:
+            visible.append(v)
+            break  # only latest patch of previous major
+
+    # 2. Last 3 minor versions of current major
+    current_minor_groups = [
+        g for g in groups.keys()
+        if g.startswith(f"{current_major}.")
+    ]
+    current_minor_groups.sort(reverse=True)
+    last_three = current_minor_groups[:3]
+
+    for minor in last_three:
+        latest_patch = groups[minor][0]  # sorted desc
+        visible.append(latest_patch)
+
+    return visible
+
+def main():
+    path = sys.argv[1] if len(sys.argv) > 1 else "versions.json"
+    versions = load_versions(path)
+
+    # In case of first run case as no versions exist yet
+    if not versions:
+        output = {
+            "visible": [],
+            "hidden": []
+        }
+        print(json.dumps(output, indent=2))
+        return
+
+    parsed, groups = group_versions(versions)
+    visible = select_visible(parsed, groups)
+    visible_strings = [f"v{v.public}" for v in visible]
+    hidden_strings = [v for v in versions if v not in visible_strings]
+
+    output = {
+        "visible": visible_strings,
+        "hidden": hidden_strings
+    }
+
+    print(json.dumps(output, indent=2))
+
+if __name__ == "__main__":
+    main()