Navigation problems with singlehtml output

[JamesRandom]

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:

1. Display for a mobile device with the menu icon

2. Navigation displayed (menu icon still visible)

3. 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]

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

[jayaddison]

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]

• 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]

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.

[jayaddison]

Another call for review of #1588 if+when anyone has time. Here's a brief recap on the problem that the modification is intended to address:

• On narrow-screen devices, the sidebar menu can take up significant screen real estate. Perhaps partly for this reason, it is hidden by default under those circumstances.
• In multi-page HTML documentation built by Sphinx, a current CSS class is added to menu items that link to the same webpage/document.
  • A JavaScript function is added as an event handler on current links, closing the menu when they are clicked.
  • The current CSS is not added to navigation links during single-page HTML documentation builds -- so the function handler is not added to them.
• Therefore, clicking a navigation menu link in a single-page HTML documentation project on a narrow-screen device does not close the navigation menu, and it is likely to obstruct visibility of the content the user chose to navigate to.

The pull request in #1588 proposes a change that alters the CSS selector query used to attach the event handlers; instead of checking for a CSS classname of current, it checks for anchor href (target) values that refer to the current page because their first character is a # (fragment identifier). This relies upon a fix included in Sphinx v8.1.0 onwards.