Support third-party serarch like Algolia, minisearch, and lyrajs

[choldgraf]

Context

Sphinx's default search UI is nice, but feels a bit out of date. It takes you to a dedicated page for search results, has non-fuzzy matching, and doesn't have a "results as you type" interface.

There are many other search libraries out there, and most of them could be adapted to the structure of this theme with the same UX around activating them (e.g. ctrl+k). This is an issue to track these options and their functionality in case we wish to implement support for them.

Algolia

Algolia has a really nice AI-powered search API that you can hook into via your own documentation site. Many documentation engines are starting to support Algolia as an option if their authors sign up for an Algolia account. This pops up an Algolia search overlay with much more rapid feedback.

For example, see the Docasaurus docs:

Algolia is pretty flexible, and should work just fine with Sphinx. To support it, I think you just need to make sure that the styling works as-expected and make it possible for the "search click" to hook into the Algolia JavaScript.

Minisearch

Minisearch is a lightweight search engine. I think we'd have to build our own UI around it?

Lyrajs

Lyrajs seems to have a bit more UI built into it.

Implementation

It think this could be implemented relatively easily by making it possible to define a different function in our search button hook:

pydata-sphinx-theme/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html

Lines 41 to 48 in 770cd3b

	{#- Only on pages not `search.html`. This is because we only want the in-page search on this page -#}
	{%- if pagename !="search" -%}
	{#- This will be hidden by default until click -#}
	<div class="search-button__overlay" onclick="toggleSearchField()"></div>
	<div class="{{ containerClass }}">
	{% include "../components/search-field.html" %}
	</div>
	{% endif %}

In the case of lyrajs or minisearch, we'd also need to add code that would build up a little in-memory search database via text. It shouldn't need to be too big since it is all text though.

References

• related to: Support readthedocs-sphinx-search #202

[12rambau]

related to #202

[agriyakhetarpal]

Hi, we have been looking into adding Algolia DocSearch to our documentation at https://docs.pybamm.org with the PyData Sphinx Theme and turns out that Algolia is providing its own Sphinx extension now which could make the process a bit easier – it is still at version 0.0.3, so it is probably not ready for production however.

[12rambau]

@choldgraf Is the solution provided in #2093 which create an internal search as you type mechanism would supersede this issue ? I'm not sure we should supports tons of search tools if we start using our own.

[maximlt]

My 2 cents and, as far as I can see, #2093 improves the search UI with "results as you type" but doesn't touch the search engine. This issue mentions both and focuses quite on the engine side by listing multiple JS engine libraries. I'd certainly like to make it easier to use and customize search engines for Sphinx sites (though I don't really know to which extent it is the responsibility of a theme).

[kaycebasques]

Hello, author of #2093 (feel free to ping me as needed)

Can confirm that #2093 does not touch the search engine. Implementation is detailed here: https://github.com/orgs/sphinx-doc/discussions/13222

It basically just intercepts the search query, uses the built-in client-side Sphinx search suite (searchtools.js) to conduct the search, and sets up a container for searchtools.js to populate the results into.

Being able to swap out the underlying search engine would be cool. Assuming that searchtools.js is one of the supported engines, I can sketch out what is and is not feasible for it to support.