From 1f03bb1b37b25ab1480ab264077650a1cc8c7b66 Mon Sep 17 00:00:00 2001
From: Jiwen Cai <jiwenc@nvidia.com>
Date: Tue, 13 Oct 2026 17:40:15 +0000
Subject: [PATCH] fix(docs): sort version dropdown branches numerically

Signed-off-by: Jiwen Cai <jiwenc@nvidia.com>
---
 docs/source/_templates/versioning.html |  2 +-
 docs/source/conf.py                    | 19 +++++++++++++++++++
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/docs/source/_templates/versioning.html b/docs/source/_templates/versioning.html
index 7954e59f49..23afbd4a87 100644
--- a/docs/source/_templates/versioning.html
+++ b/docs/source/_templates/versioning.html
@@ -7,7 +7,7 @@
 <label class="version-switcher">
   <span class="version-switcher__label">Version</span>
   <select class="version-switcher__select" onchange="location = this.value;">
-    {%- for item in versions.branches %}
+    {%- for item in sort_doc_branches(versions.branches) %}
     <option value="{{ item.url }}" {% if item == current_version %}selected{% endif %}>{{ item.name }}</option>
     {%- endfor %}
     {%- for item in versions.tags|reverse %}
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 8d0d91b47b..8c0e78365a 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -5,6 +5,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import os
+import re
 import sys
 from datetime import datetime, timezone
 
@@ -176,6 +177,23 @@ def _pip_pin(ref_name, fallback):
     "**": ["icon-links", "sidebar-nav-bs"],
 }
 
+
+def _sort_doc_branches(branches):
+    return sorted(
+        branches,
+        key=lambda item: (
+            item.name != "main",
+            tuple(map(int, re.findall(r"\d+", item.name))),
+            item.name,
+        ),
+    )
+
+
+def _versioning_context(app, pagename, templatename, context, doctree):
+    # Callables belong in page context; html_context must remain pickleable.
+    context["sort_doc_branches"] = _sort_doc_branches
+
+
 # Edit page button: link to GitHub so users can suggest edits (PyData theme uses html_context)
 html_context = {
     "github_user": "NVIDIA",
@@ -232,6 +250,7 @@ def _external_links_new_tab(app, doctree, docname):
 
 
 def setup(app):
+    app.connect("html-page-context", _versioning_context)
     app.add_role("code-file", _code_file_role)
     app.add_role("code-dir", _code_dir_role)
     app.add_config_value("html_external_links_new_tab", True, "html")