Support `readthedocs-sphinx-search`

[chrisjsewell]

Read the Docs has a search-as-you-type extension that displays a pop-up to show search results as you type. However, as we found out in https://github.com/aiidateam/aiida-core/pull/4111, there are compatibility issues with this theme.

We should make the necessary CSS changes and JavaScript changes to the theme so that this extension works "out of the box".

This would probably require a change to the JavaScript / search button trigger that is defined here:

https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html

References

• Related to: #795

[choldgraf]

+1 to improving search in this theme. I'm not quite sure what this would entail though. Is it something we can just fix with CSS or adding the right labels to HTML elements? Also just to clarify - this is the functionality that only works on readthedocs right?

[chrisjsewell]

I'm not quite sure what this would entail though

I guess just look at the code in that package; we could either work out some PR to that package, to make it bootstrap compatible, make a new package pydata-sphinx-search, or add the code directly here.

this is the functionality that only works on readthedocs right?

Try it with the RTD theme: https://readthedocs-sphinx-search.readthedocs.io , and with pydata theme: https://aiida.readthedocs.io/projects/aiida-core/en/rtd-elasticsearch. At least in some browsers, you should see that with pydata theme it shows up behind the sidebar + the formatting is all off and some other issues noted aiidateam/aiida-core#4111.

[jorisvandenbossche]

I see (in Firefox) indeed the same: two elements (the search box of the theme and the vertical line between the left sidebar and main content) seem to be "on top" of the search pop up of the extension.

The search pop-up box sets a z-index of 100000 (which I suppose is related to ensuring it is on top of all other content). But so that doesn't appear to work for those few elements of the theme.

[jorisvandenbossche]

Playing a bit with the developer tools: the sidebar (bd-sidebar) has a z-index of 1000. If I set that to a lower number, eg 0 or 100, the issue disappears.

https://github.com/pandas-dev/pydata-sphinx-theme/blob/e1eff7b428063180fe77582439cb00000094e1b0/src/scss/index.scss#L181-L194

But I don't know if that will cause other issues (or how to determine what exact number it needs to be)

[choldgraf]

I can't think of a reason for why the sidebar would need to have that high of a z-index, so long as we are doing a good job of containing the content within the other major page areas...

[choldgraf]

I updated the top comment + title a bit so that we focus it on supporting the extension that was mentioned in the top.

cc to @stsewd - maybe you would be willing to give us pointers on how this theme could support the extension natively?

[stsewd]

Hi, happy to help!

maybe you would be willing to give us pointers on how this theme could support the extension natively?

With this, do you mean to have the functionality included in the theme or to work out of the box with the theme if the extension is installed?

I see the theme already has a popup window for search.

[choldgraf]

I mean: "if the extension is installed, then instead of this theme's search bar pop-up, the readthedocs-sphinx-search pop-up would happen."

[stsewd]

I think you could check if the extension is included in the list of extensions, with that information you could conditionally disable your custom search bar and put an element that is expected by the extension (<input role="search">).

Or if you want to keep your own shortcut and manually open the search box, we could allow to change/disable the shortcut /, and expose a way to open the pop-up window with a function call (there is already one https://readthedocs-sphinx-search.readthedocs.io/en/latest/js-api-reference.html#showSearchModal, but I think we may want to scope that a little more to expose it to the public, like RTDSearch.show())

[hoechenberger]

Hello, I'm not sure if this is the correct issue to post this, but I wanted to voice that the lack of a search-as-you-type feature is what's keeping me from switching to this theme. It's very frustrating having to type out search terms, press return -- and only then figure out that you used the wrong terms or there was a typo. I, therefore, also find searching on all pydata-sphinx-theme-enabled websites a less-than-optimal experience. Hence, until this usability issue is resolved, I'll have to stick with mkdocs-material for my own stuff. Would be great to see this feature added to this theme, though -- a good search UX is one of the most essential features of good documentation.

Most of the other aspects of this theme are great, though. 👍

[choldgraf]

@hoechenberger do you know what javascript library mkdocs uses for "search as you type" Sphinx doesn't have this functionality out of the box, so we'd need to do this via some other kind of extension or modification.

I believe that @psychemedia shared this search library as well:

• https://lyrajs.io/

Might be worth checking out here. Also there's:

• https://github.com/pydata/pydata-sphinx-theme/issues/795

[thephez]

Hi, I'm very interested in this capability. The comments from last summer sounded promising, but it seems this is stalled. Just wondering if there's any hope for additional progress in the near future?

Based on a previous response I was playing around with the z-index and the hacky css below partially works. But the overlay / pydata-theme search sometimes remain open, so it's not something that can be used on our live site.

/* These are hacks to hide the pydata-theme search popup behind the readthedocs
sphinx search extension interface.
*/
.search-button__wrapper.show .search-button__search-container, 
.search-button__wrapper.show .search-button__overlay {
  z-index: 1;
}

[12rambau]

I recently realized that https://github.com/jbms/sphinx-immaterial has a tuned version of the search algorithm built-in and I would like to implement it inside this theme. It would make something workable for any type of built and not only RDT.

I effectively didn't find the time to work on it unfortunately.

[thephez]

Hi, I'm very interested in this capability. The comments from last summer sounded promising, but it seems this is stalled. Just wondering if there's any hope for additional progress in the near future?

Based on a previous response I was playing around with the z-index and the hacky css below partially works. But the overlay / pydata-theme search sometimes remain open, so it's not something that can be used on our live site.

/* These are hacks to hide the pydata-theme search popup behind the readthedocs
sphinx search extension interface.
*/
.search-button__wrapper.show .search-button__search-container, 
.search-button__wrapper.show .search-button__overlay {
  z-index: 1;
}

A further update on this. Through a combination of CSS and JS hacking I have a mostly (I think) functional integration of readthedocs-sphinx-search with this theme. Dark mode doesn't look as good as light mode - waiting on our CSS expert to fix the mess I made. We have it live now for testing on one of our less busy subprojects.

Site: https://docs.dash.org/projects/core/en/stable/ Pull request with my changes: https://github.com/dashpay/docs-core/pull/50

Hoping something here can help with a proper integration into the theme directly without all the hacky bits. :crossed_fingers:

[12rambau]

@trallard just to let you know that whenever I found some time to work back on it I would like to build an in-house solution inspiring myself from what they did in the immaterial theme. It will be complicated to get something compatible with all the potential resources on the web (algolia, RDT, etc....) Instead they rewired the classic search script into a dycamic button, clever, not too complicated and will work in any context.

[trallard]

Thank you. I went through a triaging burst and this seemed a good place for people to collaborate if they had the capacity (not trying to elbow you out of it but also being mindful of all the stuff you have in your plate 🫂)

[12rambau]

no worries, I managed to elbow myself out very well by contributing too many packages at the same time ;-)

[kaycebasques]

1977 is my proposal to provide a search-as-you-type UX built on top of Sphinx's built-in search tools

(IIRC, readthedocs-sphinx-search is now deprecated because RTD is switching to an add-ons strategy, so perhaps this particular issue can / should be closed.)

[trallard]

Thanks @kaycebasques, will close this issue in favour of #1977

[thephez]

A further update on this. Through a combination of CSS and JS hacking I have a mostly (I think) functional integration of readthedocs-sphinx-search with this theme. Dark mode doesn't look as good as light mode - waiting on our CSS expert to fix the mess I made. We have it live now for testing on one of our less busy subprojects.

Site: https://docs.dash.org/projects/core/en/stable/ Pull request with my changes: dashpay/docs-core#50

Hoping something here can help with a proper integration into the theme directly without all the hacky bits. 🤞

Hi! A brief update on my previously hacked together use of readthedocs-sphinx-search extension with this theme for anyone that's interested. I am looking forward to seeing how #1977 turns out! In the meantime, I've ported my hacks over to use the new readthedocs search addon in the PR below. Once again having some CSS troubles for dark mode, but otherwise I think it's working.

Site: https://docs.dash.org/projects/core/en/21.0.0/docs/index.html Pull request with my changes: https://github.com/dashpay/docs-core/pull/122