Layout issues in documentation (horizontal navbar)

[hoechenberger]

https://mne.tools/stable/index.html

• Version chooser doesn't display current version
• Something is wrong with the placement of the navbar elements
• Line breaks where they shouldn't be needed

This is with Safari on macOS.

[cbrnr]

The line breaks in the navbar only occur for me when the browser window is too narrow. But yes, I also think that our website is currently not very nice for the following reasons:

1. Structure
   • The sidebar is (1) too wide and (2) duplicates some things from the navbar (e.g. version, Get help). I see two options: either remove the sidebar completely (and restructure the navbar), or make it narrower and remove duplicated entries (i.e. restructure). Furthermore, the sidebar always shows a vertical scrollbar for no reason (see pydata/pydata-sphinx-theme#1238).
   • The navbar entries should be restructured. For example, no one currently manages our Mastodon and X accounts. We might just as well remove those links to conserve some horizontal space if we're not planning to use these accounts anytime soon.
   • The Search entry could just be a magnifying glass. I don't think it is that important to show the keyboard shortcut. Fixed in #12565.
2. Visual clutter
   • The Contributors should be mentioned on a separate page, not on the homepage. There is already too much visual clutter even without this list.
   • Similarly, the funders and supporting institutions sections are getting a bit overboard. I understand that this is probably required by the funders, but presumably only for current ones. Therefore, past funders could be moved to a less prominent part of the website.
   • The six feature boxes (not sure what to call them) do not have any text if you hover over them. This is a bit questionable from a UX perspective.
   • Who really needs to access all of these previous versions? My guess is probably almost no one, because users should be using the latest version. We've discussed this previously, and maybe now is the time to move everything < 1.0 to the archives.
3. Minor things
   • The highlight color (e.g. for links and active elements like the search box) seems to have changed to purple, which doesn't look great with the rest of the colors. Discussed in #12568.
   • The Discord icon is wider (25x28) than the other social icons (18x28). Fixed in #12565.

Personally, I'd switch to Material for MkDocs, because it is visually just so much better. But I guess this is too big of a change that it won't be an option (and I don't know how easy it is to import existing Sphinx stuff).

[hoechenberger]

• The six feature boxes (not sure what to call them) do not have any text if you hover over them. This is a bit questionable from a UX perspective.

From an a11y perspective, they also don't honor "reduce motion" settings of my OS/browser (in that case, the zooming motion should be disabled).

Personally, I'd switch to Material for MkDocs, because it is visually just so much better.

Not an option because we're stuck with Sphinx … 😬😵

Main advantage of Material for MkDocs for me is the search-as-you-type feature, it's such an essential thing to have these days and it's embarrassing our theme doesn't support this yet. Our search is horrendous if you don't already know what you're looking for. Progress on this feature in pydata-sphinx-theme seems to be stalled. – But that's another issue really. Let's fix the navbar for now! :)

[cbrnr]

Right, please just ignore my remark about MkDocs, this is just wishful thinking. All other points (sidebar, navbar, organization) still stand though.

[larsoner]

Version chooser doesn't display current version

This should now be fixed, the overnight builds just hadn't completed yet

For all the UI/UX stuff yes it would be great to improve any problems. PRs welcome to improve things. FWIW I can replicate the top bar stuff once I shrink my window on Linux so that part at least seems to have to do with window size and when things break (so maybe removing some social icons would already help)

vs

[hoechenberger]

FWIW I can replicate the top bar stuff once I shrink my window on Linux so that part at least seems to have to do with window size and when things break (so maybe removing some social icons would already help)

Unfortunately this doesn't seem to fix it for me on Safari on macOS: tried different screen sizes and window widths, always getting the same result

[cbrnr]

I can confirm that Safari on macOS always renders the navbar in two rows.

Edit: Same on Chrome on macOS – maybe it's a macOS thing?

[cbrnr]

Re the version chooser, for me it still shows "Choose version" instead of the actual version number.

[hoechenberger]

Re the version chooser, for me it still shows "Choose version" instead of the actual version number.

Same, I tried the devel docs

[drammock]

https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/layout.html#overview-of-theme-layout

• Version chooser doesn't display current version

I think this is because our "last updated" JS uses $ (JQuery) but JQuery isn't available, and that error causes the theme's JS that would check version and replace that text in the dropdown to not get run.

• Something is wrong with the placement of the navbar elements

html_theme_options = {..., navbar_align="left"} might fix this. https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/layout.html#configure-the-navbar-center-alignment

• Line breaks where they shouldn't be needed

Not sure what this refers to?

The sidebar is (1) too wide and (2) duplicates some things from the navbar (e.g. version, Get help).

This is not a bug, and not about the theme. Open a separate issue if you want to discuss MNE's choices about website content.

the sidebar always shows a vertical scrollbar for no reason (see pydata/pydata-sphinx-theme#1238).

Did you try the workaround in that thread? pydata/pydata-sphinx-theme#1238 (comment) If it works, PR welcome.

The navbar entries should be restructured. For example, no one currently manages our Mastodon and X accounts. We might just as well remove those links to conserve some horizontal space if we're not planning to use these accounts anytime soon.

This is not a bug, and not about the theme. Open a separate issue if you want to discuss MNE's choices about website content.

The Contributors should be mentioned on a separate page, not on the homepage. There is already too much visual clutter even without this list.

This is not a bug, and not about the theme. Open a separate issue if you want to discuss MNE's choices about website content.

Similarly, the funders and supporting institutions sections are getting a bit overboard. I understand that this is probably required by the funders, but presumably only for current ones. Therefore, past funders could be moved to a less prominent part of the website.

This is not a bug, and not about the theme. Open a separate issue if you want to discuss MNE's choices about website content.

The six feature boxes (not sure what to call them) do not have any text if you hover over them. This is a bit questionable from a UX perspective.

They do have text when you aren't hovering though... Do you mean there's no "alt" text? That said, I agree with @hoechenberger that they should respect the "minimal motion" browser setting.

Who really needs to access all of these previous versions? My guess is probably almost no one, because users should be using the latest version. We've discussed this previously, and maybe now is the time to move everything < 1.0 to the archives.

Can you link to the previous discussion / reopen it there? These omnibus issues make it really hard to keep track of everything. (Also: this is not a bug, and not about the theme).

The highlight color (e.g. for links and active elements like the search box) seems to have changed to purple, which doesn't look great with the rest of the colors.

For context on why it is purple, I invite you to read through:

• Accessibility Colour Contrast Issues pydata/pydata-sphinx-theme#1052
• Colour improvements to themes - create a scalable and accessible design system pydata/pydata-sphinx-theme#1079
• ENH - Scalable colour system for theme pydata/pydata-sphinx-theme#1174

As I said in #12565 (comment) I'm open to customizing the colors we use, but not casually and not at the expense of a11y guideline compliance.

[hoechenberger]

They do have text when you aren't hovering though... Do you mean there's no "alt" text?

Once I hover over them, I don't know what this UI element was supposed to resemble anymore, as the text is gone and the images could mean anything. The text should never disappear. My proposal would be to have the text below or above each of those tiles, and remain always visible, hovered or not.

[hoechenberger]

• Line breaks where they shouldn't be needed

Not sure what this refers to?

The top-center red circle, where it displays for me:

API
Reference

and

Get
help

(I just realized there's an inconsistency here in capitalization: Reference vs help)

[drammock]

Main advantage of Material for MkDocs for me is the search-as-you-type feature, it's such an essential thing to have these days and it's embarrassing our theme doesn't support this yet. Our search is horrendous if you don't already know what you're looking for. Progress on this feature in pydata-sphinx-theme seems to be stalled.

@hoechenberger respectfully: Words like "embarrassing" and "horrendous" are not helpful here. I know that you know how OSS works, and that features like this will only ever get implemented if someone finds (almost certainly volunteers) the time to make it happen. As a maintainer of the theme I can tell you with certainty: there are only a few of us, we all have other higher-priority responsibilities, and the backlog of bugs and feature requests is a huge source of stress. Bitter complaints like this do not help.

[hoechenberger]

As a maintainer of the theme I can tell you with certainty: there are only a few of us, we all have other higher-priority responsibilities, and the backlog of bugs and feature requests is a huge source of stress. Bitter complaints like this do not help.

I don't question that.

I do question our use of this theme when there's such obvious usability problems and lack of resources to fix them, though.

[drammock]

The top-center red circle

OK, so

Something is wrong with the placement of the navbar elements

and

Line breaks where they shouldn't be needed

are the same issue / should have the same solution I offered above (navbar_align="left")

[hoechenberger]

are the same issue / should have the same solution I offered above (navbar_align="left")

That could be, I honestly don't remember exactly what I meant :( Sorry about the confusion!!! your proposed fix seems like a good idea!

[drammock]

I do question our use of this theme when there's such obvious usability problems and lack of resources to fix them, though.

Fair enough. Please do so politely (and in a separate issue) if you want to have a serious discussion about dropping Sphinx / Pydata Sphinx Theme.

[cbrnr]

Thanks @drammock, I've fixed the navbar and sidebar scrollbar in #12571. I'll open a new issue to discuss the content/structure of the website.

[scott-huberty]

The line breaks in the navbar only occur for me when the browser window is too narrow.

Just FYI I am on a 13 inch MacBook, and the topbar line breaks occur even when setting the safari browser to full screen. So for folks like me with smaller MacBooks, the browser window will always be too narrow.

[cbrnr]

@scott-huberty did you try #12571?

[scott-huberty]

@scott-huberty did you try #12571?

No, sorry, wasn't sure if the topbar line breaks were being addressed there!

[hoechenberger]

Just FYI I am on a 13 inch MacBook, and the topbar line breaks occur even when setting the safari browser to full screen. So for folks like me with smaller MacBooks, the browser window will always be too narrow.

Just out of curiosity, do you use a "scaled resolution"? I'm on a 14" MBP and I use this setting ("one larger than default"):

[scott-huberty]

Thanks For the tip @hoechenberger - Looks like I'm just using the Default resolution, though I tried all the resolution options listed below, and none of them changed the topbar line break behavior : (

[hoechenberger]

Can you hover over that "Default" tile and let us know which resolution is displayed?

[scott-huberty]

Can you hover over that "Default" tile and let us know which resolution is displayed?

Yes, 1440 x 990

And if needed, my available resolutions (left to right) are: [1024 x 640, 1280 x 600, 1440 x 900, 1680 x 1050]

[hoechenberger]

thanks!

[cbrnr]

The navbar issue has been resolved by #12571. The only thing remaining is the version chooser. Just to be clear, the versions are correctly shown in the drop-down menu, but the issue here is that the title of the chooser should include the currently selected version (e.g. "1.7.0") as opposed to "Choose version" (please correct me if I'm wrong @hoechenberger).