From fb10c3c7291237a39ffb6eca71dc8b09057f3efd Mon Sep 17 00:00:00 2001
From: Joris Van den Bossche <jorisvandenbossche@gmail.com>
Date: Fri, 1 Oct 2021 11:44:04 +0200
Subject: [PATCH 1/4] ARROW-14189: [Docs] Add version dropdown to the sphinx
 docs

---
 docs/source/_static/versions.json            | 18 +++++++
 docs/source/_templates/docs-sidebar.html     |  2 +
 docs/source/_templates/version-switcher.html | 56 ++++++++++++++++++++
 docs/source/conf.py                          | 10 ++++
 4 files changed, 86 insertions(+)
 create mode 100644 docs/source/_static/versions.json
 create mode 100644 docs/source/_templates/version-switcher.html

diff --git a/docs/source/_static/versions.json b/docs/source/_static/versions.json
new file mode 100644
index 00000000000..f5d3fa050df
--- /dev/null
+++ b/docs/source/_static/versions.json
@@ -0,0 +1,18 @@
+[
+    {
+        "name": "5.0 (stable)",
+        "version": "5.0"
+    },
+    {
+        "version": "4.0"
+    },
+    {
+        "version": "3.0"
+    },
+    {
+        "version": "2.0"
+    },
+    {
+        "version": "1.0"
+    }
+]
\ No newline at end of file
diff --git a/docs/source/_templates/docs-sidebar.html b/docs/source/_templates/docs-sidebar.html
index f6ee66cadaa..9ae2e19031f 100644
--- a/docs/source/_templates/docs-sidebar.html
+++ b/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" >
diff --git a/docs/source/_templates/version-switcher.html b/docs/source/_templates/version-switcher.html
new file mode 100644
index 00000000000..1e6c5916127
--- /dev/null
+++ b/docs/source/_templates/version-switcher.html
@@ -0,0 +1,56 @@
+<!-- Copied from https://github.com/pydata/pydata-sphinx-theme/pull/436
+TODO update this once that is included in the upstream theme -->
+
+<div class="dropdown">
+    <button type="button" class="btn btn-primary btn-sm navbar-btn dropdown-toggle" id="switcher_button" data-toggle="dropdown">
+        {{ switcher_prefix }}{{ release }}
+        <span class="caret"></span>
+    </button>
+    <div id="switcher" class="dropdown-menu list-group-flush py-0" aria-labelledby="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(template, entry) {
+    //
+    var parts = template.split(/[\{\}]/);
+    version_ix = parts.indexOf("version");
+    language_ix = parts.indexOf("language");
+    if (version_ix >= 0) {
+        parts[version_ix] = entry.version;
+    }
+    if (language_ix >= 0) {
+        parts[language_ix] = entry.language;
+    }
+    return parts.join("");
+}
+// Function to populate the (release, language) 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) {
+            entry.url = buildURL("{{ switcher_template_url }}", entry);
+            if (!("name" in entry)) {
+                entry.name = entry.version;
+            }
+            $("#switcher").append(`<a class="list-group-item list-group-item-action py-1" href="${entry.url}">${entry.name}</a>`);
+        });
+        // see if the current page exists in the other versions of the docs
+        $.each(data, function(index, entry) {
+            let filePath = "{{ pagename }}.html";
+            $.ajax({
+                type: 'HEAD',
+                url: `${entry.url}${filePath}`,
+                // update the target URL if it exists
+                success: function() {
+                    $("#switcher").children()[index].setAttribute("href", `${entry.url}${filePath}`);
+                }
+            });
+        });
+    });
+})();
+</script>
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 2e5f9b50125..cf3f49d3c52 100644
--- a/docs/source/conf.py
+++ b/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 = []
 

From 6ec1b9836fb6e45b7f39fc63f7109edcb34ce4f6 Mon Sep 17 00:00:00 2001
From: Joris Van den Bossche <jorisvandenbossche@gmail.com>
Date: Tue, 26 Oct 2021 11:13:25 +0200
Subject: [PATCH 2/4] update to latest upstream version

---
 docs/source/_templates/version-switcher.html | 69 ++++++++++----------
 1 file changed, 36 insertions(+), 33 deletions(-)

diff --git a/docs/source/_templates/version-switcher.html b/docs/source/_templates/version-switcher.html
index 1e6c5916127..f69af31a00c 100644
--- a/docs/source/_templates/version-switcher.html
+++ b/docs/source/_templates/version-switcher.html
@@ -1,55 +1,58 @@
-<!-- Copied from https://github.com/pydata/pydata-sphinx-theme/pull/436
-TODO update this once that is included in the upstream theme -->
-
 <div class="dropdown">
-    <button type="button" class="btn btn-primary btn-sm navbar-btn dropdown-toggle" id="switcher_button" data-toggle="dropdown">
-        {{ switcher_prefix }}{{ release }}
+    <button type="button" class="btn btn-primary btn-sm navbar-btn dropdown-toggle" id="version_switcher_button" data-toggle="dropdown">
+        {{ release }}
         <span class="caret"></span>
     </button>
-    <div id="switcher" class="dropdown-menu list-group-flush py-0" aria-labelledby="switcher_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(template, entry) {
-    //
-    var parts = template.split(/[\{\}]/);
-    version_ix = parts.indexOf("version");
-    language_ix = parts.indexOf("language");
-    if (version_ix >= 0) {
-        parts[version_ix] = entry.version;
-    }
-    if (language_ix >= 0) {
-        parts[language_ix] = entry.language;
-    }
-    return parts.join("");
+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("data-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;
+    });
 }
-// Function to populate the (release, language) version switcher
+
+// 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) {
-            entry.url = buildURL("{{ switcher_template_url }}", entry);
+            // if no custom name specified (e.g., "latest"), use version string
             if (!("name" in entry)) {
                 entry.name = entry.version;
             }
-            $("#switcher").append(`<a class="list-group-item list-group-item-action py-1" href="${entry.url}">${entry.name}</a>`);
-        });
-        // see if the current page exists in the other versions of the docs
-        $.each(data, function(index, entry) {
-            let filePath = "{{ pagename }}.html";
-            $.ajax({
-                type: 'HEAD',
-                url: `${entry.url}${filePath}`,
-                // update the target URL if it exists
-                success: function() {
-                    $("#switcher").children()[index].setAttribute("href", `${entry.url}${filePath}`);
-                }
-            });
+            // 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("data-href", `${entry.url}`);
+            node.textContent = `${entry.name}`;
+            node.onclick = checkPageExistsAndRedirect;
+            $("#version_switcher").append(node);
         });
     });
 })();

From 502a39c77dcc243e7db31c7ed8250d7d15c9bada Mon Sep 17 00:00:00 2001
From: Joris Van den Bossche <jorisvandenbossche@gmail.com>
Date: Wed, 27 Oct 2021 11:07:56 +0200
Subject: [PATCH 3/4] update to latest upstream version (use href) + use
 secondary color for dropdown button

---
 docs/source/_templates/version-switcher.html | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/source/_templates/version-switcher.html b/docs/source/_templates/version-switcher.html
index f69af31a00c..297a2b0e4f4 100644
--- a/docs/source/_templates/version-switcher.html
+++ b/docs/source/_templates/version-switcher.html
@@ -1,5 +1,5 @@
 <div class="dropdown">
-    <button type="button" class="btn btn-primary btn-sm navbar-btn dropdown-toggle" id="version_switcher_button" data-toggle="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>
@@ -20,7 +20,7 @@
 // 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("data-href");
+          otherDocsHomepage = event.target.getAttribute("href");
     let tryUrl = `${otherDocsHomepage}${currentFilePath}`;
     $.ajax({
         type: 'HEAD',
@@ -32,6 +32,7 @@
     }).fail(function() {
         location.href = otherDocsHomepage;
     });
+    return false;
 }
 
 // Function to populate the version switcher
@@ -49,7 +50,7 @@
             entry.url = buildURL(entry);
             const node = document.createElement("a");
             node.setAttribute("class", "list-group-item list-group-item-action py-1");
-            node.setAttribute("data-href", `${entry.url}`);
+            node.setAttribute("href", `${entry.url}`);
             node.textContent = `${entry.name}`;
             node.onclick = checkPageExistsAndRedirect;
             $("#version_switcher").append(node);

From c3dc3fc2d8e59d4cf579f5d98d930399d6c443e6 Mon Sep 17 00:00:00 2001
From: Joris Van den Bossche <jorisvandenbossche@gmail.com>
Date: Wed, 27 Oct 2021 11:31:33 +0200
Subject: [PATCH 4/4] update versions in json file to deal with version-less
 stable docs

---
 docs/source/_static/versions.json | 20 ++++++++++++++------
 docs/source/conf.py               |  4 ++--
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/docs/source/_static/versions.json b/docs/source/_static/versions.json
index f5d3fa050df..d364cfe2714 100644
--- a/docs/source/_static/versions.json
+++ b/docs/source/_static/versions.json
@@ -1,18 +1,26 @@
 [
     {
-        "name": "5.0 (stable)",
-        "version": "5.0"
+        "name": "6.0 (stable)",
+        "version": ""
     },
     {
-        "version": "4.0"
+        "name": "5.0",
+        "version": "5.0/"
     },
     {
-        "version": "3.0"
+        "name": "4.0",
+        "version": "4.0/"
     },
     {
-        "version": "2.0"
+        "name": "3.0",
+        "version": "3.0/"
     },
     {
-        "version": "1.0"
+        "name": "2.0",
+        "version": "2.0/"
+    },
+    {
+        "name": "1.0",
+        "version": "1.0/"
     }
 ]
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index cf3f49d3c52..150cd4181d2 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -201,9 +201,9 @@
 
 html_context = {
     "switcher_json_url": "/docs/_static/versions.json",
-    "switcher_template_url": "https://arrow.apache.org/docs/{version}/",
+    "switcher_template_url": "https://arrow.apache.org/docs/{version}",
     # for local testing
-    #"switcher_template_url": "http://0.0.0.0:8000/docs/{version}/",
+    # "switcher_template_url": "http://0.0.0.0:8000/docs/{version}",
 }
 
 # Add any paths that contain custom themes here, relative to this directory.