Generate Versions JSON for new Version Switcher (#46901)

## Why are these changes needed?

In order to move away from the "Read the Docs" version switcher and to
the one provided by the PyData theme we must first have a stable JSON of
the available versions as described here:
https://github.com/google/google-java-format/releases/download/google-java-format-1.7/google-java-format-1.7-all-deps.jar

The adds helpers to custom directives in order to get the list of git
tags starting from the first one we display in the switcher then sort in
semver order. "Latest" and "master" are added to the top. This is run in
the setup fn to generate the JSON in the static folder. After this is
deployed we can reference it, add the new picker, and hide the previous
one.

## Related issue number

This is part one of a fix for
#46382 and
#46189. The follow up will
close these out.


Signed-off-by: cristianjd <[email protected]>

doc/.gitignore

@@ -21,3 +21,6 @@ source/data/api/ray.data.*.rst
 source/data/examples.rst
 source/train/examples.rst
 source/serve/examples.rst
+
+# Ignore generated versions
+source/_static/versions.json

doc/source/conf.py

@@ -25,6 +25,7 @@
     parse_navbar_config,
     setup_context,
     pregenerate_example_rsts,
+    generate_versions_json,
 )
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -483,6 +484,10 @@ def _autogen_apis(app: sphinx.application.Sphinx):
 
 
 def setup(app):
+    # Only generate versions JSON during RTD build
+    if os.getenv("READTHEDOCS") == "True":
+        generate_versions_json()
+
     pregenerate_example_rsts(app)
 
     # NOTE: 'MOCK' is a custom option we introduced to illustrate mock outputs. Since

doc/source/custom_directives.py

@@ -1,6 +1,7 @@
 import copy
 import logging
 import logging.handlers
+import os
 import pathlib
 import random
 import re
@@ -29,6 +30,9 @@
 
 from preprocess_github_markdown import preprocess_github_markdown_file
 
+import json
+from packaging.version import Version
+
 logger = logging.getLogger(__name__)
 
 __all__ = [
@@ -1252,6 +1256,63 @@ def pregenerate_example_rsts(
             )
 
 
+ray_prefix = "ray-"
+min_version = "1.11.0"
+repo_url = "https://github.com/ray-project/ray.git"
+static_dir_name = "_static"
+version_json_filename = "versions.json"
+
+
+def generate_version_url(version):
+    return f"https://docs.ray.io/en/{version}/"
+
+
+def generate_versions_json():
+    """Gets the releases from the remote repo, sorts them in semver order,
+    and generates the JSON needed for the version switcher
+    """
+
+    version_json_data = []
+
+    # Versions that should always appear at the top
+    for version in ["latest", "master"]:
+        version_json_data.append(
+            {"version": version, "url": generate_version_url(version)}
+        )
+
+    git_versions = []
+    # Fetch release tags from repo
+    output = subprocess.check_output(["git", "ls-remote", "--tags", repo_url]).decode(
+        "utf-8"
+    )
+    # Extract release versions from tags
+    tags = re.findall(r"refs/tags/(.+?)(?:\^|\s|$)", output)
+    for tag in tags:
+        if ray_prefix in tag:
+            version = tag.split(ray_prefix)[1]
+            if Version(version) >= Version(min_version):
+                git_versions.append(version)
+    git_versions.sort(key=Version, reverse=True)
+
+    for version in git_versions:
+        version_json_data.append(
+            {
+                "version": f"releases/{version}",
+                "url": generate_version_url(f"releases-{version}"),
+            }
+        )
+
+    # Ensure static path exists
+    static_dir = os.path.join(os.path.dirname(__file__), static_dir_name)
+    if not os.path.exists(static_dir):
+        os.makedirs(static_dir)
+
+    # Write JSON output
+    output_path = os.path.join(static_dir, version_json_filename)
+    with open(output_path, "w") as f:
+        json.dump(version_json_data, f, indent=4)
+
+
 REMIX_ICONS = [
     "ri-24-hours-fill",
     "ri-24-hours-line",