new navigation sidebar is effectively modal, keyboard-hostile, and hides the documentation from view

[foresto]

The not-yet-released python 3.10 and 3.11 docs theme introduces navigation sidebar behavior that is several steps backwards in usability. From what I can tell, it exhibits all these problems:

• When open, it covers up the documentation instead of letting the text reflow, making it impossible to follow my usual workflow of quickly jumping from one section to the next while reading the bits I need. The experience is like trying to navigate around modal dialog boxes in a 1990s Windows application.
• It is now inaccessible on systems without a mouse.
• Even on computers that have a mouse, viewing it is now a hassle. One must locate the mysterious hamburger button, move a hand to the mouse, aim it at the button, and click it, before the menu will appear at all. Only then can one go about looking for a needed navigation link. That's a lot of extra steps compared to simply having the links always available at the top, bottom, or side of the page.
• Scrolling through the navigation links no longer works without a mouse. Page Up/Down, arrow keys, and space bar all fail to scroll the content being read. Only mouse navigation seems to be supported.

This new design seems to have been implemented hastily, without consideration for users outside a very narrow range of workflows and devices. Please revert it, at least until something more sensible can be developed.

[JulienPalard]

Hi @foresto, I'm one of the reviewers of the PR introducing the 3.10/3.11 changes, thanks for taking the time to write some feedback.

Would you please tell us what browser (and which version) do you use? I cannot reproduce any of the mentionned issues.

[foresto]

Firefox 90 on linux.

[Mariatta]

Even on computers that have a mouse, viewing it is now a hassle. One must locate the mysterious hamburger button,

I believe the intention is that the hamburger icon should appear on smaller screen/mobile devices. Are all the issue you mentioned above only present in the mobile version, not the desktop version? Just so we understand the problem.

[foresto]

I'm not using a mobile browser, so I believe the answer is no.

Is it possible that the new theme renders a mobile experience to everyone who doesn't keep their browser window maximized or doesn't have a wide display? That would be an unfortunate mistake.

[Mariatta]

I have a larger monitor so I'm not seeing the mobile version when viewing the 3.10 docs. Perhaps it's possible to tweak the CSS. Would you mind sharing us your screen resolution?

[foresto]

My browser resolution varies from task to task, and is seldom linked to my screen resolution. I don't maximize my browser window. I often keep multiple windows side-by-side (e.g. docs, editor, and application output).

I also sometimes need the docs while on a (smaller) laptop, or when troubleshooting live code on servers with somewhat low-res screens and no mouse.

If this new theme is assuming a mobile browser based on window resolution, it's going to be wrong a lot. People read the python docs in a variety of environments, on a variety of hardware, sometimes with multitasking workflows and multiple windows. Many medium-res browsers are not phones and do not have touchscreens, but have plenty of room to display the content (if a theme hasn't hidden it).

[zware]

Patches to improve the situation for you while not reverting the usability improvements on mobile devices are more than welcome :)

In the meantime, I'll note that the links console-based browser renders docs.python.org/dev just fine regardless of window size, which may be of interest to you.

[Mariatta]

Would it be possible for us to provide a kind of "switch" so people can choose the desktop or mobile version, instead of having it detected automatically? Would that be helpful?

[foresto]

Patches to improve the situation for you while not reverting the usability improvements on mobile devices are more than welcome :)

The purpose of this bug report is not to mold the python docs to best suit me, but to point out a regression in a change that has not yet been released. Your so-called "usability improvements" break things that work today. This is your chance to fix or postpone them before impacting the general public.

Just the same, I would be disappointed to see non-mobile python programmers treated as second class citizens. I'll give it some thought if I get some free time.

In the meantime, I'll note that the links console-based browser renders docs.python.org/dev just fine regardless of window size

No, it does not. It mangles and/or discards the styling, formatting, and font rendering that make technical documentation easy to read.

[encukou]

I get the "moblie" view with a maximized window on a portrait QHD monitor with a browser sidebar. The content is about 1000px wide.

Would it be possible for us to provide a kind of "switch" so people can choose the desktop or mobile version, instead of having it detected automatically?

The old theme has a switch for the sidebar, and I do find it helpful.

[JulienPalard]

Just the same, I would be disappointed to see non-mobile python programmers treated as second class citizens.

That's not the case. The idea is not to provide a « mobile-first » experience, but a « responsive » experience, meaning: If you want to disaplay the doc in a very small window (think around the width of the actual menu) it should adapt to be easier to view.

I'm reading your initial report again, now that I understand the context:

When open, it covers up the documentation instead of letting the text reflow

Yes, there's often no point to reflow the text in a tiny-tiny-column of text, it won't be readable anyway, so maybe the switch to "cover up" should happen where it's more obvious that reflow is not wanted, like when the remaining text area is smaller than the menu width?

I'm not trying to fit the threshold so it « best suit you », I bet we'll have to doddle with it a bit before finding the sweet spot, and I also feel it could be decreased a bit. On my machine (1920 px width) it switch very soon, when it covers around 85% of my screen it already switches. What do you think @obulat?

Page Up/Down, arrow keys, and space bar all fail to scroll the content being read. Only mouse navigation seems to be supported.

Can you please try again? I tested it again, on Firefox 88, on Debian, with a brower at the right size so the menu hides, and up-down, page-up page-down and space still work for me.

[obulat]

Currently, the standard way of detecting a mobile device in CSS is using media-queries that show the screen width (not the device width). The new sidebar is shown when the screen width is less than 1023px. So, if you open the docs theme on a desktop device, and then narrow your window to less than 1023px, you will see the new menubar with the hamburger icon instead of the currently used topbar.
The value of 1023px is, indeed, wider than the usual mobile devices. The reason for choosing this width was to prevent the overflow of the top bar on screens narrower than around 1100px:

We could lower the point when the new sidebar appears to 768px (this value is used for detecting narrow devices in widely-used Bootstrap framework). This will show somewhat confusing overflow of the top bar, just like in the current version:

Can you please try again? I tested it again, on Firefox 88, on Debian, with a browser at the right size so the menu hides, and up-down, page-up page-down and space still work for me.

When you narrow down the screen on a desktop computer so that the new sidebar appears, the keyboard up-down, page-up and page-down and space work when the sidebar is closed. However, when it is open, the navigation only works within the sidebar, and you cannot close it using the keyboard.

Here is a list of possible keyboard navigation improvements for the new menu sidebar:

1. It should be impossible to tab into the sidebar when it's closed.
2. It should be possible to close the sidebar using Esc