This is an automated email from the ASF dual-hosted git repository.
gurwls223 pushed a commit to branch branch-3.5
in repository https://gitbox.apache.org/repos/asf/spark.git
The following commit(s) were added to refs/heads/branch-3.5 by this push:
new 319dff11c37 [SPARK-44742][PYTHON][DOCS] Add Spark version drop down to
the PySpark doc site
319dff11c37 is described below
commit 319dff11c373cc872aab4e7d55745561ee5d7b0e
Author: panbingkun <pbk1...@gmail.com>
AuthorDate: Wed Aug 23 11:31:22 2023 +0900
[SPARK-44742][PYTHON][DOCS] Add Spark version drop down to the PySpark doc
site
### What changes were proposed in this pull request?
The pr aims to add Spark version drop down to the PySpark doc site.
### Why are the changes needed?
Currently, PySpark documentation does not have a version dropdown. While by
default we want people to land on the latest version, it will be helpful and
easier for people to find docs if we have this version dropdown.
### Does this PR introduce _any_ user-facing change?
No.
### How was this patch tested?
Manual testing.
```
cd python/docs
make html
```
Closes #42428 from panbingkun/SPARK-44742.
Authored-by: panbingkun <pbk1...@gmail.com>
Signed-off-by: Hyukjin Kwon <gurwls...@apache.org>
(cherry picked from commit 49ba2443c118fc0322daf903b6c3370b73bcb0ce)
Signed-off-by: Hyukjin Kwon <gurwls...@apache.org>
---
python/docs/source/_static/css/pyspark.css | 13 ++++
python/docs/source/_static/versions.json | 22 +++++++
.../docs/source/_templates/version-switcher.html | 77 ++++++++++++++++++++++
python/docs/source/conf.py | 9 ++-
4 files changed, 120 insertions(+), 1 deletion(-)
diff --git a/python/docs/source/_static/css/pyspark.css
b/python/docs/source/_static/css/pyspark.css
index 89b7c65f27a..ccfe60f2bca 100644
--- a/python/docs/source/_static/css/pyspark.css
+++ b/python/docs/source/_static/css/pyspark.css
@@ -95,3 +95,16 @@ u.bd-sidebar .nav>li>ul>.active:hover>a,.bd-sidebar
.nav>li>ul>.active>a {
.spec_table tr, td, th {
border-top: none!important;
}
+
+/* Styling to the version dropdown */
+#version-button {
+ padding-left: 0.2rem;
+ padding-right: 3.2rem;
+}
+
+#version_switcher {
+ height: auto;
+ max-height: 300px;
+ width: 165px;
+ overflow-y: auto;
+}
diff --git a/python/docs/source/_static/versions.json
b/python/docs/source/_static/versions.json
new file mode 100644
index 00000000000..3d0bd148180
--- /dev/null
+++ b/python/docs/source/_static/versions.json
@@ -0,0 +1,22 @@
+[
+ {
+ "name": "3.4.1",
+ "version": "3.4.1"
+ },
+ {
+ "name": "3.4.0",
+ "version": "3.4.0"
+ },
+ {
+ "name": "3.3.2",
+ "version": "3.3.2"
+ },
+ {
+ "name": "3.3.1",
+ "version": "3.3.1"
+ },
+ {
+ "name": "3.3.0",
+ "version": "3.3.0"
+ }
+]
diff --git a/python/docs/source/_templates/version-switcher.html
b/python/docs/source/_templates/version-switcher.html
new file mode 100644
index 00000000000..16c443229f4
--- /dev/null
+++ b/python/docs/source/_templates/version-switcher.html
@@ -0,0 +1,77 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+<div id="version-button" 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/python/docs/source/conf.py b/python/docs/source/conf.py
index 38c331048e7..0f57cb37cee 100644
--- a/python/docs/source/conf.py
+++ b/python/docs/source/conf.py
@@ -177,10 +177,17 @@ autosummary_generate = True
# a list of builtin themes.
html_theme = 'pydata_sphinx_theme'
+html_context = {
+ "switcher_json_url": "_static/versions.json",
+ "switcher_template_url":
"https://spark.apache.org/docs/{version}/api/python/index.html";,
+}
+
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-#html_theme_options = {}
+html_theme_options = {
+ "navbar_end": ["version-switcher"]
+}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@spark.apache.org
For additional commands, e-mail: commits-h...@spark.apache.org
