[Docs] New PyData Sphinx theme update bugs

[AlenkaF]

Describe the bug, including details regarding any error messages, version, and platform.

The Sphinx theme we have been using (PyData Sphinx Theme) has been pinned to an older version for a while now and with the PR merged this week we have updated the code and are now using version 0.14.0 for the dev docs.

There are some issues that need to be fixed by the code freeze in 2 weeks. Will keep a list of those in this issue. Feel free to comment here and add extra bugs you might come across.

List of issues on the new dev site:

• Change header size (top nav bar) for smaller screens, see [Docs] New PyData Sphinx theme update bugs #37947 (comment) [Docs] Reduce width of header items and keep header height default (small) on smaller screens #38209
• Version switcher button in the nav bar prints "Choose version" instead of the version you are currently have open (dev in our case), see [Docs] New PyData Sphinx theme update bugs #37947 (comment) [Docs] version_match should match the version from versions.json #38240

Component(s)

Documentation

[jorisvandenbossche]

Top navigation bar and version warning bar are overlapping. The top navbar also overlaps the top content.

You need to do a hard refresh .. (for me ctrl-F5), and then it all looks nice (we had the same issue a while ago with the documentation version switcher: #37357). It's a bit annoying though

[AlenkaF]

Oh, I can not believe I already forgot about that!
Thank you for reminding me and adding info to the issue for others to see.

It works nicely for me now (no overlapping, no white background in the dark mode grid cards).

Should we keep this open if anything else pops up or do we close it?

[jorisvandenbossche]

Let's maybe keep this issue open as the place to gather feedback or (design) bugs with the new theme.

[jorisvandenbossche]

One thing that doesn't work (unless this is intended to work differently in the version switcher of the theme) is showing the version of the docs you are looking at in the switcher:

While on the stable or older docs it shows the version:

[jorisvandenbossche]

We could maybe also limit the size of the header / image when we are on a smaller screen, eg in mobile mode:

(that's our overriding of --pst-header-height, it might be possible to only do that when on wide screens)

[AlenkaF]

Regarding the version switcher - if I look at the theme web page the "Choose version" is displayed for stable version and "dev" for development. Older versions are using the old theme so can't tell.

Will check if that is something we can change on our side.

And for the header size, I agree. Will also add it to the TODO list on this issue description and see what I can do to fix it.

[pitrou]

Same issue here with the top bar vertical size, which also hides part of the side navigation panels as soon as I scroll down:

[AlenkaF]

I think this will happen in any case when the window gets so small that it uses double header size, see the original theme:

If we find it very annoying I can open up an issue on the PyData theme repo.

[pitrou]

Well, besides the vertical footprint, the problem is that it hides part of the side navigation panels as soon as one scrolls down.

[AlenkaF]

Yes, I think that happens in the original theme also - could you check the picture I added in the previous comment just to check I am thinking of the correct part of the side navigation being hidden?

[pitrou]

I never encountered it in the original theme.

[pitrou]

I'm thinking about these ones below:

[AlenkaF]

Here? (with the original theme I mean PyData Sphinx Theme)

.
.
.
and scrolling down
.
.
.

[pitrou]

Ahah, yes, exactly.

[jorisvandenbossche]

Well, besides the vertical footprint, the problem is that it hides part of the side navigation panels as soon as one scrolls down.

If the header hides part of the sidebar when it becomes larger because of wrapping around on a second line, that sounds as a bug in the theme itself, IMO, and something we can report upstream.
(not sure if that's something that would be easy to solve, though)

[AlenkaF]

Oh, you are actually right Antoine. In our dev docs the sidebar gets hidden very soon when scrolling the page (not at the start, if you do not scroll down though!). But in the original theme it only happens when one gets to the end of the content.

I guess this actually does happen because of the increased header height due to our logo.

I am not sure if this is actually a bug or not, but will trust Joris on it.

We could also use a different logo ourselves (for example: Chevron-only). In this case there will be no need to resize the header. In the current case, when using horizontal version of the logo), the logo gets very small and Apache part of it is not readable if the size is not increased.

[AlenkaF]

Oh, you are actually right Antoine. In our dev docs the sidebar gets hidden very soon when scrolling the page (not at the start, if you do not scroll down though!). But in the original theme it only happens when one gets to the end of the content.

No, sorry, wrong again. I had a bigger window and the top navbar was only single header 🤦‍♀️ It actually happens in the original theme also - as is visible on the pictures I added before.

[AlenkaF]

... something we can report upstream.
(not sure if that's something that would be easy to solve, though)

Agree, will add an issue upstream 👍

[AlenkaF]

Upstream issue for the hidden sidebar top item when scrolling: pydata/pydata-sphinx-theme#1493

[AlenkaF]

I have opened a PR for the first item on the list (Change header size (top nav bar) for smaller screens) here: #38148.

I haven't found a solution for the second item on the list (Version switcher button in the nav bar prints "Choose version" instead of the version you are currently have open (dev in our case)) so I have opened an issue upstream: pydata/pydata-sphinx-theme#1500.

In case we do not find a solution for the version switcher text today, I would suggest to merge the PR for the header height on smaller screens to have it in the 14.0.0 release.

[jorisvandenbossche]

We could maybe also rename "Specifications and Protocol" to just "Specifications", that also makes the header a bit shorter, and thus less quickly to wraparound.

[AlenkaF]

Closing this issue as both reported bugs have been fixed:

• GH-38209: [Docs] Reduce width of header items and keep header height default (small) on smaller screens #38148
• GH-38240: [Docs] version_match should match the version from versions.json #38241