GH-36590: [Docs] Support Pydata Sphinx Theme 0.14.0

[AlenkaF]

Preview: http://crossbow.voltrondata.com/pr_docs/36591/

Rationale for this change

The Pydata Sphinx Theme that we use for our documentation has been pinned due to bigger changes in the theme layout. It needs to be unpinned and our layout needs to be updated.

What changes are included in this PR?

Update of the Pydata Sphinx Theme and changes to our layout/structure:

• dark/light mode
• top menu bar
• search button in the top right navigation bar
• drop down from the theme layout in the top right navigation bar
• version warnings bar from the theme layout
• main landing page and the landing page for the dev docs

⚠️ Needs an update of the versions.json

Are these changes tested?

Yes, locally. Will also add docs preview via GitHub actions.

Are there any user-facing changes?

No.

• Closes: [Docs] Enable dark mode on documentation site #32451
• Closes: [Docs] Support Pydata Sphinx Theme 0.14.0 #36590

[AlenkaF]

@github-actions crossbow submit preview-docs

[github-actions]

Revision: 67c8e5e

Submitted crossbow builds: ursacomputing/crossbow @ actions-12e0914bc0

Task	Status
preview-docs

[AlenkaF]

[jorisvandenbossche]

How does this differ from the default?

[AlenkaF]

The default is "navbar_end": ["navbar-icon-links"] (https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/layout.html#header-sections).

[AlenkaF]

I have played around with the logo a bit because it is not clearly visible if located on the top navbar. It might make sense to keep it on the left side bar as is (see picture below).

Regarding the navigation bar dropdown, the picture here is an example without extra index page for the supported environments section but using header_links_before_dropdown to organise all languages and cookbooks in a dropdown link named More. I find that it doesn't really make a difference though I like it better if the menu item is titled Supported environments and not More.

[jorisvandenbossche]

Regarding the navigation bar dropdown, the picture here is an example without extra index page for the supported environments section but using header_links_before_dropdown to organise all languages and cookbooks in a dropdown link named More. I find that it doesn't really make a difference though I like it better if the menu item is titled Supported environments and not More.

Yes, if we do this, we should certainly ensure we can call it something more informative than "More". But assume for a moment we can do that (it might require an upstream change, though). In that case, for me the biggest difference is when you go for example to the Python section of the docs. With this dropdown, the left sidebar should now only show links relevant to Python, not all other languages?

I have played around with the logo a bit because it is not clearly visible if located on the top navbar. It might make sense to keep it on the left side bar as is (see picture below).

Yes, it's indeed not very big .. Putting the logo on the sidebar gives a bit strange effect for the top navbar though, I find (with the navigation items being above the logo).
Another option might be to make the navbar or navbar img a bit larger, which I think is something that numpy did (https://github.com/numpy/numpy/blob/0febb4c40e98dc6fe35c7bcd672d0a6c438cd5c8/doc/source/_static/numpy.css#L3-L8)

[AlenkaF]

With this dropdown, the left sidebar should now only show links relevant to Python, not all other languages?

Oh, that is true! Will use the dropdown then and see what can be done with the title of the button.

Another option might be to make the navbar or navbar img a bit larger ...

Yes, I think that would be a good option also.

[AlenkaF]

Yes, if we do this, we should certainly ensure we can call it something more informative than "More". But assume for a moment we can do that (it might require an upstream change, though)

Opened an issue for it: pydata/pydata-sphinx-theme#1386

[AlenkaF]

@github-actions crossbow submit preview-docs

[AlenkaF]

[github-actions]

Revision: 8b40a3e

Submitted crossbow builds: ursacomputing/crossbow @ actions-21674461bf

Task	Status
preview-docs

[12rambau]

I have played around with the logo a bit because it is not clearly visible if located on the top navbar. It might make sense to keep it on the left side bar as is (see picture below).

If you needed another rational for not putting the logo in the left sidebar, it will be invisible on small screen where the left sidebar is hidden by default. I was just passing by, I'll see what we can do with @AlenkaF issue in the theme itself.

[AlenkaF]

Thank you @12rambau for the information about the left sidebar and the issue in the theme (more of a feature request really)!
Regarding the logo, we increased the header height and it works very well 👍

[AlenkaF]

Regarding the custom colors in our theme_overrides.css

arrow/docs/source/_static/theme_overrides.css

Lines 24 to 31 in 63644f4

	--pst-color-active-navigation: 215, 70, 51;
	--pst-color-link-hover: 215, 70, 51;
	--pst-color-headerlink: 215, 70, 51;
	/* Use normal text color (like h3, ..) instead of primary color */
	--pst-color-h1: var(--color-text-base);
	--pst-color-h2: var(--color-text-base);
	/* Use softer blue from bootstrap's default info color */
	--pst-color-info: 23, 162, 184;

The css color styles used currently are quite different then what the theme used before, see color variables for version 0.8 vs new color variables structure.

Currently the theme uses primary and secondary theme colors that are meant to complement one another visually across the whole theme (light and dark separately) plus some extra like "info", "warning", "success", ... but much less then in the old version of the theme.

Comparing the custom colors we have set in Apache Arrow to the colors in the new theme:

• active navigation is red rgb(215, 70, 51) in our custom css and is light blue / primary rgb(69, 157, 185) in the new pydata sphinx theme
• link hover is is also red rgb(215, 70, 51) currently and is orange/secondary rgb(238, 144, 64) in the new theme
• I am not sure about the headerlink color. It is also defined to red currently, but am not sure how to match it with the new theme
• h1 and h2 color is black rgb(51, 51, 51) currently and is light blue / primary rgb(69, 157, 185) in the new pydata sphinx theme
• info color is light blue rgb(23, 162, 184) currently and is almost identical to the primary light blue rgb(69, 157, 185) in the new theme

What I suggest is to remove all css variables from our custom css and maybe change the secondary theme color to our current red rgb(215, 70, 51).

[jorisvandenbossche]

Regarding colors, now we are updating it, it might be worth to directly check with the latest development version of the theme, as I know the colors are being overhauled (https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/install.html#development-version).
(and for example, I think in the theme the h1 and h2 headers are now also black, like we did on our side)

[jorisvandenbossche]

@github-actions crossbow submit preview-docs

[github-actions]

Revision: 125215b

Submitted crossbow builds: ursacomputing/crossbow @ actions-4ab7e303d8

Task	Status
preview-docs

[jorisvandenbossche]

OK, let's give this a go on the development docs, so we still have some time to fine tune before the 14.0 release. Thanks a lot Alenka!

[conbench-apache-arrow]

After merging your PR, Conbench analyzed the 5 benchmarking runs that have been run so far on merge-commit 7dc9f69.

There were no benchmark performance regressions. 🎉

The full Conbench report has more details.