[SPARK-42853][DOC] Updating the Style for the Spark Docs based on the Webpage #40269

grundprinzip · 2023-03-03T16:08:12Z

What changes were proposed in this pull request?

The website was recently released with a new style. This patch adopts the same style for the docs page.

How was this done?

The main website and the docs page are built on bootstrap for styling. This means that particular styles applied to the main page will work nicely on the docs page as well. The biggest chunk of work was to simply copy the stylesheet, the long tail was some manual adjustments.

Copy the main stylesheet from the new website and drop it into the docs build
Remove the old CSS from the layout
Update the layout to use the new bootstrap 5 instead of the old bootstrap
Use bootstrap for tab visibility instead of home-grown JS
Use bootstrap for table striping instead of custom CSS
Update all 139 tables to have a proper thead to render nicely
Keep the navigation bar top fixed, with a body top padding.
Copied minor CSS properties from the old stylesheet to the new one to handle the folding side bar menu.
Using bootstrap from CDN instead of local

Images

Why are the changes needed?

Style

Does this PR introduce any user-facing change?

No

How was this patch tested?

Browser

gengliangwang · 2023-03-04T03:07:01Z

@grundprinzip Thanks for the work. +1 for the approach.
Could you point out where is exactly the same as the PR apache/spark-website#359 so that we can review this PR easier?

Also, I notice the tabs need adjustment:
this PR:

current:

gengliangwang · 2023-03-04T03:10:28Z

There is also differences on the top bar and left menu when scrolling down the page:
Take https://spark.apache.org/docs/3.3.2/sql-ref-ansi-compliance.html as an example, of this PR:

Current:

grundprinzip · 2023-03-11T10:42:18Z

@gengliangwang I fixed the issues you mentioned, I left an explanation in the PR desc to explain what exactly I did, but I'm not sure what you mean with:

Could you point out where is exactly the same as the PR apache/spark-website#359 so that we can review this PR easier?

grundprinzip · 2023-03-11T10:45:15Z

docs/_layouts/global.html

          <link rel="canonical" href="{{page.redirect}}" />
        {% endif %}

-        <link rel="stylesheet" href="css/bootstrap.min.css">


Removes the old bootstrap style.

grundprinzip · 2023-03-11T10:45:29Z

docs/_layouts/global.html

-        <meta name="viewport" content="width=device-width">
-        <link rel="stylesheet" href="css/main.css">

+        <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet"


using the same config as in the website

grundprinzip · 2023-03-11T10:46:00Z

docs/_layouts/global.html

-                    <div class="navbar-brand"><a href="index.html">
-                        <img src="img/spark-logo-hd.png" style="height:50px;"/></a><span class="version">{{site.SPARK_VERSION_SHORT}}</span>
-                    </div>
+        <nav class="navbar navbar-expand-lg navbar-dark p-0 px-4 fixed-top" style="background: #1d6890;" id="topbar">


some slight changes to the navbar to adjust for newer bootstrap version.

grundprinzip · 2023-03-11T10:46:52Z

docs/_layouts/global.html

+            </div>
+        </nav>
+
+        {% if page.url == "/" %}


To give the intro page a bit more spice, I'm using the hero banner as on the main webpage with the colors. This only appears when the index page is called.

gengliangwang · 2023-03-17T22:00:55Z

docs/_layouts/global.html

+            </button>
+            <div class="collapse navbar-collapse" id="navbarCollapse">
+                <ul class="navbar-nav me-auto">
+                    <!--TODO(andyk): Add class="active" attribute to li some how.-->


nit: let's remove the old TODO?

docs/_layouts/global.html

gengliangwang · 2023-03-17T22:23:14Z

docs/configuration.md


 While numbers without units are generally interpreted as bytes, a few are interpreted as KiB or MiB.
-See documentation of individual configuration properties. Specifying units is desirable where 
+See documentation of individual configuration properties. Specifying units is desirable where


BTW there are many changes for trimming spaces in this PR. I go over them and they look fine. It would be great to update the editor to only trim the spaces of the modified lines in the future.

gengliangwang · 2023-03-17T22:24:00Z

@grundprinzip This one LGTM overall. Could you create a Spark jira for it and update the PR title?

gengliangwang · 2023-03-19T18:33:58Z

Thanks, merging to master

…r all code snippets (Spark 3.4 and below) ### What changes were proposed in this pull request? This PR proposes to recover the availity of switching languages consistently across docs for all code snippets in Spark 3.4 and below by using the proper class selector in the JQuery. Previously the selector was a string `.nav-link tab_python` which did not comply multiple class selection: https://www.w3.org/TR/CSS21/selector.html#class-html. I assume it worked as a legacy behaviour somewhere. Now it uses the standard way `.nav-link.tab_python`. Note that #42657 works because there's only single class assigned (after we refactored the site at #40269) ### Why are the changes needed? This is a regression in our documentation site. ### Does this PR introduce _any_ user-facing change? Yes, once you click the language tab, it will apply to the examples in the whole page. ### How was this patch tested? Manually tested after building the site. ![Screenshot 2023-09-19 at 12 08 17 PM](https://github.com/apache/spark/assets/6477701/09d0c117-9774-4404-8e2e-d454b7f700a3) ### Was this patch authored or co-authored using generative AI tooling? No. Closes #42989 from HyukjinKwon/SPARK-45210. Authored-by: Hyukjin Kwon <gurwls223@apache.org> Signed-off-by: Hyukjin Kwon <gurwls223@apache.org> (cherry picked from commit 796d878) Signed-off-by: Hyukjin Kwon <gurwls223@apache.org>

…r all code snippets (Spark 3.4 and below) ### What changes were proposed in this pull request? This PR proposes to recover the availity of switching languages consistently across docs for all code snippets in Spark 3.4 and below by using the proper class selector in the JQuery. Previously the selector was a string `.nav-link tab_python` which did not comply multiple class selection: https://www.w3.org/TR/CSS21/selector.html#class-html. I assume it worked as a legacy behaviour somewhere. Now it uses the standard way `.nav-link.tab_python`. Note that #42657 works because there's only single class assigned (after we refactored the site at #40269) ### Why are the changes needed? This is a regression in our documentation site. ### Does this PR introduce _any_ user-facing change? Yes, once you click the language tab, it will apply to the examples in the whole page. ### How was this patch tested? Manually tested after building the site. ![Screenshot 2023-09-19 at 12 08 17 PM](https://github.com/apache/spark/assets/6477701/09d0c117-9774-4404-8e2e-d454b7f700a3) ### Was this patch authored or co-authored using generative AI tooling? No. Closes #42989 from HyukjinKwon/SPARK-45210. Authored-by: Hyukjin Kwon <gurwls223@apache.org> Signed-off-by: Hyukjin Kwon <gurwls223@apache.org>

…r all code snippets (Spark 3.4 and below) ### What changes were proposed in this pull request? This PR proposes to recover the availity of switching languages consistently across docs for all code snippets in Spark 3.4 and below by using the proper class selector in the JQuery. Previously the selector was a string `.nav-link tab_python` which did not comply multiple class selection: https://www.w3.org/TR/CSS21/selector.html#class-html. I assume it worked as a legacy behaviour somewhere. Now it uses the standard way `.nav-link.tab_python`. Note that #42657 works because there's only single class assigned (after we refactored the site at #40269) ### Why are the changes needed? This is a regression in our documentation site. ### Does this PR introduce _any_ user-facing change? Yes, once you click the language tab, it will apply to the examples in the whole page. ### How was this patch tested? Manually tested after building the site. ![Screenshot 2023-09-19 at 12 08 17 PM](https://github.com/apache/spark/assets/6477701/09d0c117-9774-4404-8e2e-d454b7f700a3) ### Was this patch authored or co-authored using generative AI tooling? No. Closes #42989 from HyukjinKwon/SPARK-45210. Authored-by: Hyukjin Kwon <gurwls223@apache.org> Signed-off-by: Hyukjin Kwon <gurwls223@apache.org> (cherry picked from commit 796d878) Signed-off-by: Hyukjin Kwon <gurwls223@apache.org>

…r all code snippets (Spark 3.4 and below) ### What changes were proposed in this pull request? This PR proposes to recover the availity of switching languages consistently across docs for all code snippets in Spark 3.4 and below by using the proper class selector in the JQuery. Previously the selector was a string `.nav-link tab_python` which did not comply multiple class selection: https://www.w3.org/TR/CSS21/selector.html#class-html. I assume it worked as a legacy behaviour somewhere. Now it uses the standard way `.nav-link.tab_python`. Note that apache#42657 works because there's only single class assigned (after we refactored the site at apache#40269) ### Why are the changes needed? This is a regression in our documentation site. ### Does this PR introduce _any_ user-facing change? Yes, once you click the language tab, it will apply to the examples in the whole page. ### How was this patch tested? Manually tested after building the site. ![Screenshot 2023-09-19 at 12 08 17 PM](https://github.com/apache/spark/assets/6477701/09d0c117-9774-4404-8e2e-d454b7f700a3) ### Was this patch authored or co-authored using generative AI tooling? No. Closes apache#42989 from HyukjinKwon/SPARK-45210. Authored-by: Hyukjin Kwon <gurwls223@apache.org> Signed-off-by: Hyukjin Kwon <gurwls223@apache.org>

### What changes were proposed in this pull request? After #40269, there is no border in the generated tables of Spark doc(for example, https://spark.apache.org/docs/latest/sql-ref-ansi-compliance.html) . This PR is to fix it by restoring part of the table style in https://github.com/apache/spark/pull/40269/files#diff-309b964023ca899c9505205f36d3f4d5b36a6487e5c9b2e242204ee06bbc9ce9L26 This PR also unifies all the styles of tables by removing the `class="table table-striped"` in HTML style tables in markdown docs. ### Why are the changes needed? Fix a regression in the table CSS of Spark docs ### Does this PR introduce _any_ user-facing change? No ### How was this patch tested? Manually build docs and verify. Before changes: <img width="931" alt="image" src="https://github.com/apache/spark/assets/1097932/1eb7abff-65af-4c4c-bbd5-9077f38c1b43"> After changes: <img width="911" alt="image" src="https://github.com/apache/spark/assets/1097932/be77d4c6-1279-43ec-a234-b69ee02e3dc6"> ### Was this patch authored or co-authored using generative AI tooling? Generated-by: ChatGPT 4 Closes #44096 from gengliangwang/fixTable. Authored-by: Gengliang Wang <gengliang@apache.org> Signed-off-by: Gengliang Wang <gengliang@apache.org>

### What changes were proposed in this pull request? After #40269, there is no border in the generated tables of Spark doc(for example, https://spark.apache.org/docs/latest/sql-ref-ansi-compliance.html) . This PR is to fix it by restoring part of the table style in https://github.com/apache/spark/pull/40269/files#diff-309b964023ca899c9505205f36d3f4d5b36a6487e5c9b2e242204ee06bbc9ce9L26 This PR also unifies all the styles of tables by removing the `class="table table-striped"` in HTML style tables in markdown docs. ### Why are the changes needed? Fix a regression in the table CSS of Spark docs ### Does this PR introduce _any_ user-facing change? No ### How was this patch tested? Manually build docs and verify. Before changes: <img width="931" alt="image" src="https://github.com/apache/spark/assets/1097932/1eb7abff-65af-4c4c-bbd5-9077f38c1b43"> After changes: <img width="911" alt="image" src="https://github.com/apache/spark/assets/1097932/be77d4c6-1279-43ec-a234-b69ee02e3dc6"> ### Was this patch authored or co-authored using generative AI tooling? Generated-by: ChatGPT 4 Closes #44097 from gengliangwang/fixTable3.5. Authored-by: Gengliang Wang <gengliang@apache.org> Signed-off-by: Gengliang Wang <gengliang@apache.org>

After apache/spark#40269, there is no border in the generated tables of Spark doc(for example, [sql-ref-ansi-compliance.html](https://spark.apache.org/docs/latest/sql-ref-ansi-compliance.html)) . Currently only the doc of Spark 3.5.0 is affected. This PR is to apply the changes in apache/spark#44096 on the current Spark 3.5.0 doc by 1. change the `site/docs/3.5.0/css/custom.css` 2. Execute `sed -i '' 's/table class="table table-striped"/table/' *.html` under `site/docs/3.5.0/` directory. This should be a safe change. I have verified it on my local env.

### What changes were proposed in this pull request? After apache#40269, there is no border in the generated tables of Spark doc(for example, https://spark.apache.org/docs/latest/sql-ref-ansi-compliance.html) . This PR is to fix it by restoring part of the table style in https://github.com/apache/spark/pull/40269/files#diff-309b964023ca899c9505205f36d3f4d5b36a6487e5c9b2e242204ee06bbc9ce9L26 This PR also unifies all the styles of tables by removing the `class="table table-striped"` in HTML style tables in markdown docs. ### Why are the changes needed? Fix a regression in the table CSS of Spark docs ### Does this PR introduce _any_ user-facing change? No ### How was this patch tested? Manually build docs and verify. Before changes: <img width="931" alt="image" src="https://github.com/apache/spark/assets/1097932/1eb7abff-65af-4c4c-bbd5-9077f38c1b43"> After changes: <img width="911" alt="image" src="https://github.com/apache/spark/assets/1097932/be77d4c6-1279-43ec-a234-b69ee02e3dc6"> ### Was this patch authored or co-authored using generative AI tooling? Generated-by: ChatGPT 4 Closes apache#44096 from gengliangwang/fixTable. Authored-by: Gengliang Wang <gengliang@apache.org> Signed-off-by: Gengliang Wang <gengliang@apache.org>

### What changes were proposed in this pull request? Enhance the Visual Appeal of Spark doc website after #40269: #### 1. There is a weird indent on the top right side of the first paragraph of the Spark 3.5.0 doc overview page Before this PR <img width="680" alt="image" src="https://github.com/apache/spark/assets/1097932/84d21ca1-a4d0-4bd4-8f20-a34fa5db4000"> After this PR: <img width="1035" alt="image" src="https://github.com/apache/spark/assets/1097932/4ffc0d5a-ed75-44c5-b20a-475ff401afa8"> #### 2. All the titles are too big and therefore less readable. In the website https://spark.apache.org/downloads.html, titles are h2 while in doc site https://spark.apache.org/docs/latest/ titles are h1. So we should make the font size of titles smaller. Before this PR: <img width="935" alt="image" src="https://github.com/apache/spark/assets/1097932/5bbbd9eb-432a-42c0-98be-ff00a9099cd6"> After this PR: <img width="965" alt="image" src="https://github.com/apache/spark/assets/1097932/dc94c1fb-6ac1-41a8-b4a4-19b3034125d7"> #### 3. The banner image can't be displayed correct. Even when it shows up, it will be hover by the text. To make it simple, let's not show the banner image as we did in https://spark.apache.org/docs/3.4.2/ <img width="570" alt="image" src="https://github.com/apache/spark/assets/1097932/f6d34261-a352-44e2-9633-6e96b311a0b3"> <img width="1228" alt="image" src="https://github.com/apache/spark/assets/1097932/c49ce6b6-13d9-4d8f-97a9-7ed8b037be57"> ### Why are the changes needed? Improve the Visual Appeal of Spark doc website ### Does this PR introduce _any_ user-facing change? No ### How was this patch tested? Manually build doc and verify on local setup. ### Was this patch authored or co-authored using generative AI tooling? No Closes #44642 from gengliangwang/enhance_doc. Authored-by: Gengliang Wang <gengliang@apache.org> Signed-off-by: Hyukjin Kwon <gurwls223@apache.org>

new style

3517888

github-actions bot added the DOCS label Mar 3, 2023

grundprinzip added 2 commits March 3, 2023 17:08

fixes

fed85db

missing image

4078774

grundprinzip added 2 commits March 10, 2023 19:47

fixing tables

b280fa0

removing old style sheet

8ac0476

grundprinzip commented Mar 11, 2023

View reviewed changes

grundprinzip changed the title ~~[WIP][DOC] Updating the Style for the Spark Docs based on the Webpage~~ [DOC] Updating the Style for the Spark Docs based on the Webpage Mar 16, 2023

grundprinzip added 2 commits March 16, 2023 09:15

merge

e6ec5b2

table

1d4ccda

gengliangwang reviewed Mar 17, 2023

View reviewed changes

docs/_layouts/global.html Show resolved Hide resolved

gengliangwang reviewed Mar 17, 2023

View reviewed changes

docs/_layouts/global.html Show resolved Hide resolved

gengliangwang reviewed Mar 17, 2023

View reviewed changes

grundprinzip changed the title ~~[DOC] Updating the Style for the Spark Docs based on the Webpage~~ [SPARK-42853][DOC] Updating the Style for the Spark Docs based on the Webpage Mar 19, 2023

grundprinzip added 2 commits March 19, 2023 10:20

removing todo

4e6528c

Merge remote-tracking branch 'origin/master' into HEAD

c874430

srowen approved these changes Mar 19, 2023

View reviewed changes

gengliangwang approved these changes Mar 19, 2023

View reviewed changes

gengliangwang closed this in 12b9b77 Mar 19, 2023

HyukjinKwon mentioned this pull request Sep 19, 2023

[SPARK-45210][DOCS][3.4] Switch languages consistently across docs for all code snippets (Spark 3.4 and below) #42989

Closed

gengliangwang mentioned this pull request Nov 30, 2023

[SPARK-46188][Doc] Fix the CSS of Spark doc's generated tables #44096

Closed

This was referenced Nov 30, 2023

[SPARK-46188][Doc][3.5] Fix the CSS of Spark doc's generated tables #44097

Closed

Fix the CSS of Spark 3.5.0 doc's generated tables apache/spark-website#492

Merged

gengliangwang mentioned this pull request Jan 9, 2024

[SPARK-46637][DOCS] Enhancing the Visual Appeal of Spark doc website #44642

Closed

[SPARK-42853][DOC] Updating the Style for the Spark Docs based on the Webpage #40269

[SPARK-42853][DOC] Updating the Style for the Spark Docs based on the Webpage #40269

Uh oh!

Conversation

grundprinzip commented Mar 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes were proposed in this pull request?

How was this done?

Images

Why are the changes needed?

Does this PR introduce any user-facing change?

How was this patch tested?

Uh oh!

gengliangwang commented Mar 4, 2023

Uh oh!

gengliangwang commented Mar 4, 2023

Uh oh!

grundprinzip commented Mar 11, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gengliangwang commented Mar 17, 2023

Uh oh!

gengliangwang commented Mar 19, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

grundprinzip commented Mar 3, 2023 •

edited

Loading