Document Algolia DocSearch integration

[hammer]

Description / Summary

I would like to use Algolia's DocSearch to get fast typeahead on our search box. There are instructions for how to integrate DocSearch with the RTD theme at readthedocs/sphinx_rtd_theme#761. I have tried to modify the CSS/JS for this theme but I can't make it work.

Value / benefit

This would allow users of this theme to have fast typeahead on their search box.

Implementation details

I have tried using inputSelector: '#search-input' in the JS and #search-input { overflow: visible; } in the CSS, but this does not work.

Tasks to complete

No response

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[hammer]

I noticed while investigating this issue that the #search-input element has an autocomplete attribute that's currently set to off. I don't see any documentation on this attribute; do I perhaps need to set it to on? I tried doing that manually with Chrome developer tools and it didn't seem to help, but just thought I'd ask.

[hammer]

Okay strangely after a reload this is actually working now! The styling is not great as the search result text is cut off at the sidebar. If anyone with frontend skills sees this issue, I'd love your assistance making this look good...

[choldgraf]

@hammer - did you ever get this one working? I agree it would be excellent to document this pattern. If there is some CSS tweaks we can make to improve the algolia search UI, then I'd be +1 on adding those in this theme.

[hammer]

@choldgraf we did in fact get this working! https://github.com/pystatgen/sgkit/pull/668 is the PR and you can try it live at https://pystatgen.github.io/sgkit/latest/.

From a styling perspective the only tricky part is to make the results box overflow the left sidebar. It would probably be better to have the search box on a topbar, similar to what you have on your personal site, but that level of customization is beyond my skill level.

We still need to figure out how to restrict the typeahead to a specific version, and it would be nice to tweak how some content is ranked and displayed, but overall I think the typeahead is a better search experience than having a separate search results page. Although I also haven't figured out how to get to a search results page with this plugin, you seem to have to open one of the typehead results...

[choldgraf]

whooooah it is beautiful! If you have a chance to write some short docs about the steps you followed, I am happy to review a PR!