Navigation problems with singlehtml output

JamesRandom commented 4 years ago

I have two, possibly related, issues with navigation when generating singlehtml output.

Firstly, when clicking on the top-level entry in the navigation bar, it does not automatically open to display the lower levels. Clicking on the [+] icon does. Clicking on lower level entries does automatically open them.

This is a relatively minor UI annoyance/inconsistency but it seems to also cause a major problem on small screens for mobile devices.

In this case, clicking on the menu icon at the top of the page displays the navigation bar. Clicking on a top-level entry goes to that location but does not close the menu. Worse, the menu icon has disappeared and it is impossible to hide the navigation bar. It seems it is not possible to scroll back to the top of the document.

The contents page can be redisplayed by either refreshing the page or by clicking on the [+] icon next to one of the top-level entries, then selecting a sub-entry. This correctly goes to that heading and closes the menu.

This makes singlehtml output unusable.

Reproducible Project

The attached example with an index file, a couple of content files and a minimal conf.py demonstrates the problem.

rst-files.zip

Error Logs/Results

The attached image files show:

Display for a mobile device with the menu icon
Navigation displayed (menu icon still visible)
After clicking on an entry (correct location displayed on right of page but hidden by navigation menu)

Environment Info

Python Version: 3.7.6
Sphinx Version: 2.4.2
RTD Theme Version: 0.4.3

Running MacOS Catalina. Checked results in a couple of browsers (Chrome and Safari) with identical results.

stsewd commented 4 years ago

I was able to replicate this, the menu disappearing is weird

jayaddison commented 4 months ago

To the best of my knowledge:

This only appears to affect singlehtml builds because for multi-page html builds, a menu item navigation click causes the browser to re-display the page contents from scratch, meaning that the sidebar menu reappears in the default closed position.
There is an existing event handler in theme.js that, based on a comment in there (// Close menu when you click a link.), seems intended to handle these navigation events.
The mentioned event-handler doesn't appear to get attached to any sidebar menu hyperlinks when I open the singlehtml build output in Firefox. Whether that's due to a regression somewhere, I don't know, but the cause is an empty resultset from the .wy-menu-vertical .current ul li a CSS selector query.

This affects some documentation in Debian, and I've provided a patch downstream in the relevant bugthread at https://bugs.debian.org/1075914 for that (although I'm not 100% certain whether it's the best way to fix this!).

also, cc'ing @kebekus @nienn (because this seems similar to #1177 which I was reading before discovering this more-relevant bugreport)

jayaddison commented 4 months ago

This only appears to affect singlehtml builds because for multi-page html builds, a menu item navigation click causes the browser to re-display the page contents from scratch, meaning that the sidebar menu reappears in the default closed position.

There is an exception to this: hyperlinks to the same .html page that is already being viewed in the web browser. This is intended, I think, to be exactly the set of items with the current CSS class applied to them.

Given that, I think my downstream patch is incorrect (and I've added a message to note that there). Instead of removing the .current part of the query unconditionally, a couple of options that occur to me are either to add the current CSS to the root of the table-of-contents tree in the sidebar (this would be a Sphinx upstream change, and could affect other themes), or -- and I don't really like this, but am suggesting it since it may be feasible -- detect that the project is singlehtml in the JS code, and conditionally omit the .current part of the query in that case.

Although I think it's worth being careful about side-effects, and would benefit from discussion, initially I lean towards the idea of adjusting this behaviour in Sphinx. In single-document Sphinx builds there isn't really a logical notion of current location within the graph of documents, so it might be valid to consider the root of the table-of-contents tree as the current location.

jayaddison commented 3 weeks ago

If anyone from this thread has time to test the potential fix in #1588, I'd be grateful!

Strictly speaking, it only resolves the second part of the reported navigation problems; selectively-quoting the relevant part of the bugreport:

Clicking on a top-level entry goes to that location but does not close the menu.

readthedocs / sphinx_rtd_theme