[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?