Search and version selection not visible on initial page load

[mattclay]

The search and version selection scrolls with the left side bar. Unfortunately this results in some pages showing no search or version selection on initial page load, and with no visible indication that it even exists.

Example: https://docs.ansible.com/ansible-core/2.14/dev_guide/testing/sanity/integration-aliases.html

Here's what the initial page load looks like under Firefox on macOS.

The version selection and search box should always be visible, regardless of the scroll position of the navigation or content.

[ssbarnea]

@mattclay I was not able to reproduce the bug with https://sphinx-ansible-theme.readthedocs.io so I assume that issue is specific to the docs.ansible.com, not the theme itself. That repo is not maintained by docs team.

[mattclay]

@ssbarnea I was able to reproduce with that page. You just need to make the browser window very short (since there's nothing significant in the left navigation bar). If the left navigation bar has more content, then the browser window doesn't need to be as short to reproduce the issue.

[felixfontein]

I can reproduce this; to see the selectors, I have to scroll to the bottom of the page and then back to the beginning. I cannot reproduce this with https://sphinx-ansible-theme.readthedocs.io/en/latest/, which confirms my initial thought when seeing this, namely that this is caused by the sphinx_rtd_theme this one extends. Also https://docs.ansible.com/ansible-core/devel/dev_guide/testing/sanity/integration-aliases.html does not have this problem either (the ansible-core devel build uses unrestricted dependencies, while all other ansible-core and ansible docsite builds use restricted dependencies).

Personally I don't like the behavior of the latest sphinx_rtd_theme that much either, since there's no scrollbar on the sidebar container that's now scrollable independently. IMO this is horrible UX... I have to click into the sidebar (on something that isn't clickable) and use the keyboard to scroll it. (I don't use the touchpad and have no mouse wheel on my laptop, thus there is no other way to scroll that part for me.)

[felixfontein]

Hmmmm, what is strange is that the Ansible devel docsite build does use sphinx_rtd_theme 1.2.0, which is the latest version of the sphinx_rtd_theme. It (https://docs.ansible.com/ansible/devel/dev_guide/testing/sanity/integration-aliases.html) shows the same problem for me.

My new guess is that this is caused by Sphinx itself, even though indirectly. The docsite build uses Sphinx 5.3.0, while the latest version (used by ansible-core devel docsite build and probably also https://sphinx-ansible-theme.readthedocs.io/en/latest/) is 7.0.0. My current guess is that this is caused indirectly by Sphinx 6.0.0 removing jQuery, and sphinx_rtd_theme using that to do the scrolling. The thing is that for me, the JS console for ansible-core devel docsite shows Uncaught ReferenceError: jQuery is not defined; tracking to where jQuery is needed in sphinx_rtd_theme shows

  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable({{ 'true' if theme_sticky_navigation|tobool else 'false' }});
      });
  </script>

The sphinx_ansible_theme sets sticky_navigation=True (https://github.com/ansible-community/sphinx_ansible_theme/blob/v0.10.2/src/sphinx_ansible_theme/theme.conf#L11), which also happens to be the default for sphinx_rtd_theme. And indeed, https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/long.html shows exactly the same problem, and that one has jquery loaded.

So TLDR: the problem is the sticky_navigation setting, which has been enabled for this theme (same as for sphinx_rtd_theme) by default. And the reason it works fine for the ansible-core devel docsite is 'random luck', since some requirements (among them the jquery extension for sphinx) aren't installed.

[felixfontein]

Hmm, turning off sticky_navigation does something else. I tried this with my own docsite, where I added:

html_theme_options = {
    'sticky_navigation': False,
}

(I've undid the change since then, so it's no longer visible.) It still moves the sidebar initially to the current navigation index, but doesn't scroll it anymore, so even scrolling to the bottom of the page and back up won't scroll the sidebar. It has to be scrolled to the top explicitly to see the search bar.

It seems that this behavior cannot be turned off, except by removing that code from the RTD theme (or adding more JS code which scrolls back after the RTD theme scrolled - which is hacky). So it seems this is an issue with the RTD theme we don't have control over.