ARROW-14189: [Docs] Add version dropdown to the sphinx docs

docs/source/_static/versions.json

@@ -0,0 +1,26 @@
+[
+    {
+        "name": "6.0 (stable)",
+        "version": ""
+    },
+    {
+        "name": "5.0",
+        "version": "5.0/"
+    },
+    {
+        "name": "4.0",
+        "version": "4.0/"
+    },
+    {
+        "name": "3.0",
+        "version": "3.0/"
+    },
+    {
+        "name": "2.0",
+        "version": "2.0/"
+    },
+    {
+        "name": "1.0",
+        "version": "1.0/"
+    }
+]

docs/source/_templates/docs-sidebar.html

@@ -3,6 +3,8 @@
   <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
 </a>
 
+{% include "version-switcher.html" %}
+
 <form class="bd-search d-flex align-items-center" action="{{ pathto('search') }}" method="get">
   <i class="icon fas fa-search"></i>
   <input type="search" class="form-control" name="q" id="search-input" placeholder="{{ theme_search_bar_text }}" aria-label="{{ theme_search_bar_text }}" autocomplete="off" >

docs/source/_templates/version-switcher.html

@@ -0,0 +1,60 @@
+<div class="dropdown">
+    <button type="button" class="btn btn-secondary btn-sm navbar-btn dropdown-toggle" id="version_switcher_button" data-toggle="dropdown">
+        {{ release }}
+        <span class="caret"></span>
+    </button>
+    <div id="version_switcher" class="dropdown-menu list-group-flush py-0" aria-labelledby="version_switcher_button">
+    <!-- dropdown will be populated by javascript on page load -->
+    </div>
+</div>
+
+<script type="text/javascript">
+// Function to construct the target URL from the JSON components
+function buildURL(entry) {
+    var template = "{{ switcher_template_url }}";  // supplied by jinja
+    template = template.replace("{version}", entry.version);
+    return template;
+}
+
+// Function to check if corresponding page path exists in other version of docs
+// and, if so, go there instead of the homepage of the other docs version
+function checkPageExistsAndRedirect(event) {
+    const currentFilePath = "{{ pagename }}.html",
+          otherDocsHomepage = event.target.getAttribute("href");
+    let tryUrl = `${otherDocsHomepage}${currentFilePath}`;
+    $.ajax({
+        type: 'HEAD',
+        url: tryUrl,
+        // if the page exists, go there
+        success: function() {
+            location.href = tryUrl;
+        }
+    }).fail(function() {
+        location.href = otherDocsHomepage;
+    });
+    return false;
+}
+
+// Function to populate the version switcher
+(function () {
+    // get JSON config
+    $.getJSON("{{ switcher_json_url }}", function(data, textStatus, jqXHR) {
+        // create the nodes first (before AJAX calls) to ensure the order is
+        // correct (for now, links will go to doc version homepage)
+        $.each(data, function(index, entry) {
+            // if no custom name specified (e.g., "latest"), use version string
+            if (!("name" in entry)) {
+                entry.name = entry.version;
+            }
+            // construct the appropriate URL, and add it to the dropdown
+            entry.url = buildURL(entry);
+            const node = document.createElement("a");
+            node.setAttribute("class", "list-group-item list-group-item-action py-1");
+            node.setAttribute("href", `${entry.url}`);
+            node.textContent = `${entry.name}`;
+            node.onclick = checkPageExistsAndRedirect;
+            $("#version_switcher").append(node);
+        });
+    });
+})();
+</script>

docs/source/conf.py

@@ -127,6 +127,9 @@
 release = os.environ.get('ARROW_DOCS_VERSION',
                          pyarrow.__version__)
 
+if "+" in release:
+    release = release.split(".dev")[0] + " (dev)"
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -196,6 +199,13 @@
     "google_analytics_id": "UA-107500873-1",
 }
 
+html_context = {
+    "switcher_json_url": "/docs/_static/versions.json",
+    "switcher_template_url": "https://arrow.apache.org/docs/{version}",
+    # for local testing
+    # "switcher_template_url": "http://0.0.0.0:8000/docs/{version}",
+}
+
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []