Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] New PyData Sphinx theme update bugs #37947

Closed
2 tasks done
AlenkaF opened this issue Sep 29, 2023 · 22 comments
Closed
2 tasks done

[Docs] New PyData Sphinx theme update bugs #37947

AlenkaF opened this issue Sep 29, 2023 · 22 comments

Comments

@AlenkaF
Copy link
Member

AlenkaF commented Sep 29, 2023

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:

Component(s)

Documentation

@jorisvandenbossche
Copy link
Member

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

@jorisvandenbossche jorisvandenbossche added this to the 14.0.0 milestone Sep 29, 2023
@jorisvandenbossche jorisvandenbossche added the Priority: Blocker Marks a blocker for the release label Sep 29, 2023
@AlenkaF
Copy link
Member Author

AlenkaF commented Sep 29, 2023

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
Copy link
Member

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

@jorisvandenbossche
Copy link
Member

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:

image

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

image

@jorisvandenbossche
Copy link
Member

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

image

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

@AlenkaF
Copy link
Member Author

AlenkaF commented Sep 29, 2023

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
Copy link
Member

pitrou commented Oct 2, 2023

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

@AlenkaF
Copy link
Member Author

AlenkaF commented Oct 3, 2023

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

Screenshot 2023-10-03 at 09 33 10

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

@pitrou
Copy link
Member

pitrou commented Oct 3, 2023

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

@AlenkaF
Copy link
Member Author

AlenkaF commented Oct 3, 2023

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
Copy link
Member

pitrou commented Oct 3, 2023

I never encountered it in the original theme.

@pitrou
Copy link
Member

pitrou commented Oct 3, 2023

I'm thinking about these ones below:

sphinx-theme2

@AlenkaF
Copy link
Member Author

AlenkaF commented Oct 3, 2023

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

Screenshot 2023-10-03 at 10 10 19
.
.
.
and scrolling down
.
.
.
Screenshot 2023-10-03 at 10 10 26

@pitrou
Copy link
Member

pitrou commented Oct 3, 2023

Ahah, yes, exactly.

@jorisvandenbossche
Copy link
Member

jorisvandenbossche commented Oct 3, 2023

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
Copy link
Member Author

AlenkaF commented Oct 3, 2023

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
Copy link
Member Author

AlenkaF commented Oct 3, 2023

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
Copy link
Member Author

AlenkaF commented Oct 3, 2023

... 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
Copy link
Member Author

AlenkaF commented Oct 4, 2023

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

@AlenkaF
Copy link
Member Author

AlenkaF commented Oct 9, 2023

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.

@AlenkaF AlenkaF removed this from the 14.0.0 milestone Oct 10, 2023
@jorisvandenbossche jorisvandenbossche added this to the 14.0.0 milestone Oct 10, 2023
@jorisvandenbossche
Copy link
Member

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 AlenkaF closed this as completed Dec 13, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants