This is an automated email from the ASF dual-hosted git repository.
gurwls223 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/spark.git
The following commit(s) were added to refs/heads/master by this push:
new 94a31bd9c144 [SPARK-48809][PYTHON][DOCS] Reimplemented `spark version
drop down` of the `PySpark doc site` and fix bug
94a31bd9c144 is described below
commit 94a31bd9c144da16f4fe5d42a709c1dc415e1277
Author: panbingkun <[email protected]>
AuthorDate: Tue Jan 14 12:52:55 2025 +0900
[SPARK-48809][PYTHON][DOCS] Reimplemented `spark version drop down` of the
`PySpark doc site` and fix bug
### What changes were proposed in this pull request?
The pr aims to using `pydata_sphinx_theme`'s `embedded` `version-switcher`
to reimplement `spark version drop down` of the `PySpark doc site` and fix bug
for `4.0.0-preview1`'s python api docs.
### Why are the changes needed?
- When I was reviewing `4.0.0-preview1`'s docs, I found that `spark
version drop down of the PySpark doc site` is no longer usable (when clicking,
`the dropdown menu` will no longer display), as follows:
https://spark.apache.org/docs/4.0.0-preview1/api/python/index.html
<img width="1164" alt="image"
src="https://github.com/apache/spark/assets/15246973/e4bf241b-180b-4f03-aec3-809ebb697faf";>
With the continuous updates of sphinx and its dependent component
versions that generate Python documents, the `version-switcher` originally
implemented by custom extensions is no longer usable, and we need to fix it
- After
<img width="1384" alt="image"
src="https://github.com/apache/spark/assets/15246973/40d37913-a23c-43a4-b95e-391ad4a0edc9";>
**It looks more in line with the current theme `CSS style` and looks more
`beautiful`**
- In addition, to cooperate with this fix, we need to update the content of
the `spark-website/site/static/versions.json` file, as follows:
<img width="494" alt="image"
src="https://github.com/apache/spark/assets/15246973/fc25af5a-34e0-4c05-8476-3557510cda27";>
**I will complete it in another separate PR**
The modified file `versions.json` will be compatible with the
implementation of `spark 3.5.1` and the `new implementation`.
https://github.com/apache/spark/blob/310f8ea2456dad7cec0f22bfed05a679764c3d7e/python/docs/source/_templates/version-switcher.html#L63-L73
### Does this PR introduce _any_ user-facing change?
No.
### How was this patch tested?
Manually test.
### Was this patch authored or co-authored using generative AI tooling?
No.
Closes #47214 from panbingkun/SPARK-48809.
Lead-authored-by: panbingkun <[email protected]>
Co-authored-by: panbingkun <[email protected]>
Signed-off-by: Hyukjin Kwon <[email protected]>
---
python/docs/source/_static/css/pyspark.css | 13 ----
.../docs/source/_templates/version-switcher.html | 77 ----------------------
python/docs/source/conf.py | 18 ++---
3 files changed, 9 insertions(+), 99 deletions(-)
diff --git a/python/docs/source/_static/css/pyspark.css
b/python/docs/source/_static/css/pyspark.css
index 565eaea29935..6f47dd80e950 100644
--- a/python/docs/source/_static/css/pyspark.css
+++ b/python/docs/source/_static/css/pyspark.css
@@ -91,16 +91,3 @@ 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/_templates/version-switcher.html
b/python/docs/source/_templates/version-switcher.html
deleted file mode 100644
index 16c443229f4b..000000000000
--- a/python/docs/source/_templates/version-switcher.html
+++ /dev/null
@@ -1,77 +0,0 @@
-<!--
-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 5640ba151176..20c13cd768de 100644
--- a/python/docs/source/conf.py
+++ b/python/docs/source/conf.py
@@ -188,19 +188,19 @@ autodoc_typehints = "none"
# a list of builtin themes.
html_theme = 'pydata_sphinx_theme'
-html_context = {
- # When releasing a new Spark version, please update the file
- # "site/static/versions.json" under the code repository "spark-website"
- # (item should be added in order), and also set the local environment
- # variable "RELEASE_VERSION".
- "switcher_json_url": "https://spark.apache.org/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 = {
+ "check_switcher": False,
+ "switcher": {
+ # When releasing a new Spark version, please update the file
+ # "site/static/versions.json" under the code repository "spark-website"
+ # (item should be added in order), and also set the local environment
+ # variable "RELEASE_VERSION".
+ "json_url": "https://spark.apache.org/static/versions.json";,
+ "version_match": release,
+ },
"header_links_before_dropdown": 6,
"navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
"footer_start": ["spark_footer", "sphinx-version"],
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
