Is there a shortcut to focus on the Search field on docs.python.org?

I primarily use docs.python.org for Python docs and it’s a bit annoying that I have to use mouse to change keyboard focus to the Search field.

Is there a shortcut that I’m missing?

I dunno, but I second the motion. Preferably ‘/‘, like in GMail or vim.

3 Likes

It is /, see HTML Theming — Sphinx documentation under the basic theme.

A

1 Like

Doesn’t work for me in Safari 16 / macOS 11.7

For some reason, keyboard navigation is turned off for the pydoctheme.

If you look at
https://docs.python.org/3/_static/documentation_options.js it uses this
setting:

NAVIGATION_WITH_KEYS: false
3 Likes

Using the TAB key usually jumps to various input fields. In my browser
(firefox) 3 TABs gets me to the search field. I can also right click on
that field and make a “keyword search” shortcut for it; I’ve just done
that and now I can type “py3 some search stuff here” in the location/URL
bar and have it run the docs.python.org search. So now I don’t even need
to go there to start my search.

But yet, I guess a key binding to something like “/” would also be nice.

Cheers,
Cameron Simpson cs@cskk.id.au

1 Like

navigation_with_keys=False is the default it seems, and python-docs-theme doesn’t override it.

A

I could write my own browser extension.

Yet I think it should work out of the box. And the docs engine seems to support it.

There’s no one-size-fits-all answer. I personally get annoyed by
sites which implement their own random keybindings, because I rely
heavily on a keyboard navigation extension (pentadactyl) which
allows me to directly switch input focus to any element of a page
with my keyboard already, and “/” is used for in-page content
searching. For pages which think they know better than their users
when it comes to how they should use a keyboard, I end up having to
force shift into raw input mode so that JS won’t intercept
keypresses. Honestly, I wish browsers had a feature like “no really
don’t send my keypresses directly to any page’s scripts unless I
expressly allow it.”

3 Likes

I personally much preferred the old style, which auto-selected the search field. But from what I recall, that is problematic for accessibility, so couldn’t be retained. I agree, having a keyboard way of getting to the search field (something better than “tab until you get there”) would be great. If it’s just enabling a setting, then +1 from me.

And me. - Cameron

Upon a bit of investigation, ENABLE_SEARCH_SHORTCUTS: true which specifically enables the search shortcuts is set in the JS options for Python 3.11, presumably due to the more recent Sphinx version, which I was just about to finally get around to upgrade for 3.10.

As such, / for search is already enabled and works, but only at narrower widths (with the full width search bar), not at full-screen desktop width. This is because the theme uses two different search bars for the different widths, both with the same <input> name property value, which is what Sphinx’s JS is looking for to know what input field to jump to. As such, so only the narrow-width one (which happens to be first in the HTML) gets focused regardless of whether it is the currently displayed one–you can see the code under focusSearchBar() here.

This would presumably best be hacked around on the theme side, but there isn’t one super-obvious best way to do it, since changing which search bar is shown is done with all CSS, but the change would need to be done in JS. There are a few options here:

  • Install an event handler on resize to change the name of the search fields depending on which is not display: none. Perhaps the most obvious solution, but hacky, inefficient and possibly unreliable

  • Install an event handler in both search fields to fire on focus, which switches to the other field if the current field is display: none. A lot less inefficient and likely more reliable, since it only fires once when the shortcut is pressed

  • Simplest and most efficient of all, just stick the following in e.g. sidebar.js (or some new JS file) to override the Documentation.focusSearchBar() function with:

    Documentation.focusSearchBar = () => $('input[name=q]:visible').first().focus();
    

    I tested and confirmed it works; only downside is it depends to some extent on the Sphinx JS, whereas the first two don’t. However, it could also potentially get upstreamed into Sphinx (using somewhat less trivial vanilla ES6, ofc), since it seems generally reasonable to select the first visible search field rather than the first overall…or perhaps at least some less hacky way for themes to override the behavior.

3 Likes

Thanks for the investigation, please could you report it to python-docs-theme?

(And / works at https://devguide.python.org, which uses the Furo theme.)

Hmm, I only get sidebar-search-bar on https://devguide.python.org: when the window is narrow (< ~1085px) there is no full-width-search-bar but sidebar-search-bar is still available via the burger button.

I was going to, yeah, but wanted to get @AA-Turner 's input from an upstream Sphinx perspective before pursuing the otherwise-preferred third alternative (presumably using vanilla JS rather than jQuery).

It does at full width, but at narrower width, it doesn’t automatically open the hidden-by-default sidebar in which the search box is found, so while focus does move there, and you can actually enter and submit your search query as normal, the user can’t actually see this happening, so its not very user friendly.

@pradyunsg , do you think it would be possible to add a keypress event handler for / on the Furo side to toggle the sidebar open, so the search bar is visible?

I’m a little confused by what you intend to mean here, sorry. You mention the devguide and it sounds like you might be intending to describe behavior consistent with what I also saw there, but the passage you quoted is referring to the behavior on docs.python.org.

1 Like

You mentioned that “/ is already enabled and works”. I tested both docs and devguide in both wide and narrow windows and it didn’t for me.

Okay, that wasn’t at all clear to me, sorry. Keep in mind, as I mention above (but didn’t make as clear as I intended to), it only works on the Python 3.11+ docs (i.e. not on the Python 3.10 docs, which are currently the default selected version). It still should work on the devguide, though, as tested by both @hugovk and myself, so perhaps your browser, extensions or configuration are blocking the JS or its interception of the keystrokes? Or perhaps it has to do with a keyboard layout/input mode issue?

Ah, that’s it: I didn’t realize that the selector loads different version / configuration of sphinx.

1 Like

Yeah, different versions of Sphinx can used to build the documentation in each branch (though I’m going to update 3.10, the earliest branch still built, to match the others). However, that still doesn’t explain why it isn’t working for you in the devguide…there could be several reasons there, but mostly machine/browser/config-specific so hard to pinpoint.

The shortcut works for me on devguide, just that the search field is hidden when window is too narrow.