This is an automated email from the ASF dual-hosted git repository.
kszucs pushed a commit to branch release-6.0.0
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/release-6.0.0 by this push:
new 0d599fa ARROW-14189: [Docs] Add version dropdown to the sphinx docs
0d599fa is described below
commit 0d599fa40b84a4089e8c6b44d49f3e98deacbaa9
Author: Joris Van den Bossche <[email protected]>
AuthorDate: Wed Oct 27 16:41:57 2021 +0200
ARROW-14189: [Docs] Add version dropdown to the sphinx docs
Closes #11283 from jorisvandenbossche/ARROW-14189-version-dropdown
Authored-by: Joris Van den Bossche <[email protected]>
Signed-off-by: Krisztián Szűcs <[email protected]>
---
docs/source/_static/versions.json | 26 ++++++++++++
docs/source/_templates/docs-sidebar.html | 2 +
docs/source/_templates/version-switcher.html | 60 ++++++++++++++++++++++++++++
docs/source/conf.py | 10 +++++
4 files changed, 98 insertions(+)
diff --git a/docs/source/_static/versions.json
b/docs/source/_static/versions.json
new file mode 100644
index 0000000..d364cfe
--- /dev/null
+++ b/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/"
+ }
+]
\ No newline at end of file
diff --git a/docs/source/_templates/docs-sidebar.html
b/docs/source/_templates/docs-sidebar.html
index f6ee66c..9ae2e19 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 0000000..297a2b0
--- /dev/null
+++ b/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>
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 2e5f9b5..150cd41 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -127,6 +127,9 @@ version = os.environ.get('ARROW_DOCS_VERSION',
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 @@ html_theme_options = {
"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 = []
