search

pydata / pydata-sphinx-theme

A clean, three-column Sphinx theme with Bootstrap for the PyData community
https://pydata-sphinx-theme.readthedocs.io
BSD 3-Clause "New" or "Revised" License
600 stars 313 forks source link

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

Open choldgraf opened 2 years ago

choldgraf commented 2 years ago

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:

chrome_WVfEMbiNLI

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:

https://github.com/pydata/pydata-sphinx-theme/blob/770cd3b0374680fd6f48ef66e6fb1ab795866f2c/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html#L41-L48

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

12rambau commented 2 years ago

related to https://github.com/pydata/pydata-sphinx-theme/issues/202

agriyakhetarpal commented 1 year ago

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.