[Doc] The nav bar on the right side is not activated correctly when I clicked it

[rkooo567]

Description

When I clicked the nav bar on the right side of the documentation, it redirects me correctly, but incorrectly activated.

cc @maximsmol @angelinalg

Link

No response

[hora-anyscale]

Per Triage Sync: @maxpumperla assigning to you

[peytondmurray]

This is due to a bug in an upstream dependency: executablebooks/sphinx-book-theme#678. Investigating workarounds now.

[peytondmurray]

I looked into updating to sphinx-book-theme==1.0.1, the latest version. Happily, we can upgrade now without any conflicts with other dependencies, and it indeed solves the issue. We also would gain a lot of other benefits of upgrading; see #37944 for the issue dedicated to upgrading doc dependencies.

The downside is that the docs look completely different, a change that is way outside the scope of this issue and would best be discussed in the issue mentioned above. The other issue is that upgrading sphinx-book-theme is a problem with generate_nav_html, used in the sbt-sidebar-nav.html template:

       {{- generate_nav_html(
              startdepth=0,
              kind="sidebar",
              maxdepth=4,
              collapse=True,
              includehidden=True,
              titles_only=True,
              show_nav_level=theme_show_navbar_depth) }}

throws an exception. I'm not sure where this function is defined, but anyway we can't make use of it as-is. So we'd have to solve that issue as well.

For now I'm going to see if we can make a workaround with some other method (JS?)

[peytondmurray]

After looking into this further, the issue is in how bootstrap's ScrollSpy behaves. Some people have reported that modifying a CSS rule seems to fix it, but when I load our docs I don't see any conflicting CSS rule here :/. I tried setting the appropriate rule anyway, but didn't see any change. This is supposed to get fixed in a later version of sphinx-book-theme anyway, so I think it might just be best to focus on upgrading our frontend build system entirely.

[peytondmurray]

@maxpumperla @rkooo567 Now that #41115 is merged, can we close this? To be totally clear, this still won't always work as you might expect - for example, if there are two headings close to the bottom of the page, and you click on the last one, the second-to-last heading might be highlighted in the secondary sidebar because that's the heading the top of the window is closest to. But I think in most cases the behavior is sensible, so can we close this one out?

[peytondmurray]

Closing this as complete - haven't heard of complaints about this yet with the new docs site. Please reopen if this is an issue.