Clarify how a downstream theme could support this

[choldgraf]

I was looking into how the pydata sphinx theme could support this search functionality, but was a bit confused by the documentation so asking questions here to help clarify.

The custom search input docs

Suggest that you need a structure like this:

<div role="search">
   <form action="search.html" method="get">
      <input type="text" name="q" placeholder="Search docs" />
   </form>
</div>

However, in the pydata theme, we have a little button that will pop up a search window, rather than a search field:

Clicking this button, or typing Ctrl+K will cause the search window to pop up:

It has this structure:

<button class="btn btn-sm navbar-btn search-button search-button__button" title="" aria-label="Search" data-toggle="tooltip" data-original-title="Search">
  <i class="fa-solid fa-magnifying-glass"></i>
</button>

Do we need to find some way to put an input in there for this to work? Or can we somehow get the sphinx RTD search to work with the button some other way?

[ericholscher]

@choldgraf The docs say that it attachs to an input element with the search role. So I think you just need to add role="search" to it. The code looks for an input below that:

readthedocs-sphinx-search/sphinx_search/static/js/rtd_sphinx_search.js

Lines 435 to 438 in 225353f

	inputField = document.querySelector("[role='search'] input");
	if (inputField === undefined || inputField === null) {
	throw "'[role='search'] input' not found";
	}

There's definitely a chance that this will conflict with our hotkey integration in the extension, but we are definitely interested in making it work nicely.

[choldgraf]

Sorry I did have clarified - the "input" thing is what I wasn't sure about. Because our buttons are just buttons, there is no input field inside them. Does that mean that this won't work w the extension? Or that we'd need to nest an empty and visible input field or something?

[ericholscher]

@choldgraf presumably the input is the text field that the search term goes in after the popup is launched? Changing the integration to trigger on other actions shouldn't be hard, but might take a small change to the code. We can definitely look into this next week.

[choldgraf]

Ya - there is an input field on the page, it is just not nested inside the search button. It exists in a standalone spot and is simply revealed when the search button is pressed.

[humitos]

I just wanted to chime in into this conversation to let you know that are working on a new "js client" that will include all the Read the Docs Addons integrations: flyout, analytics, search as you type, etc.

This is not ready for users/authors to start using/integrating it yet; but I wanted to comment here in case you want to chime in there and follow the conversation/design.

• Repository: https://github.com/readthedocs/readthedocs-client
• How to communicate with the js client discussion: User API: communicate with the library addons#13
• Initial test for the pattern (using WebElements) that all the addons (e.g. Search) may follow: Warning CSS improvements and illustration of patterns addons#37

It will be super helpful for us getting feedback from you so we can build something that's easy to integrate for theme authors and easy to use for writers 😉 . Note that this is a work-in-progress work and things will change a lot, but having feedback at this early stage could be helpful for us.

[choldgraf]

Oh nice - pinging @12rambau and @drammock who may also have thoughts, and probably more time than me since I'm the one with an infant now 🙂