Add Algolia DocSearch to our site

[hammer]

https://docsearch.algolia.com/

I've already applied, they're going to send me a JS snippet to put on our site to enable indexing. We should get a nice typeahead for our search box once this goes live.

[jeromekelleher]

Nice, looking forward to seeing the results.

[hammer]

For future reference here are the docs on getting it set up https://docsearch.algolia.com/docs/dropdown.

[hammer]

DocSearch is ready! I will see if I can do the integration myself...

[hammer]

I got a note from Algolia on September 9 saying that they're going to stop crawling our site on September 23 if we don't get search implemented before then.

I took a look at the integration and it's non-trivial. There's some discussion on search, Algolia, Sphinx, and the RTD theme:

• Add Algolia search Plugin sphinx-doc/sphinx#3812
• How to configure Search? jupyter-book/jupyter-book#1242
• Document how to use the Algolia DocSearch service jupyter-book/jupyter-book#1324
• Example: adding Algolia Docsearch to a Sphinx setup that uses 'sphinx_rtd_theme' readthedocs/sphinx_rtd_theme#761

Unfortunately I don't see any discussion specific to our theme https://github.com/executablebooks/sphinx-book-theme.

The Algolia email:

Copy the following CSS/JS snippets and add them to your page

<!-- at the end of the HEAD -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />

<!-- at the end of the BODY -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script type="text/javascript"> docsearch({
apiKey: '<REDACTED>',
indexName: 'sgkit',
inputSelector: '### REPLACE ME ####',
debug: false // Set debug to true if you want to inspect the dropdown
});
</script>

[hammer]

I spent a bit of time yesterday and today figuring this out and I have hit the limits of my frontend knowledge. I filed executablebooks/sphinx-book-theme#394 upstream, so hopefully some kind soul will reply there.

[hammer]

Lol turns out that worked, I just needed to clear some cache. If y'all think a slightly ugly and suboptimal typeahead is a good idea, let's try it out. If not, we can put this on hold for a bit until we get some styling hints.

In addition to styling, I also think we'll want to exclude the index from being crawled and searched, since it generates duplicate entries in the typeahead.

[hammer]

To customize the crawling process, we can modify https://github.com/algolia/docsearch-configs/blob/master/configs/sgkit.json. Documentation for this file is at https://docsearch.algolia.com/docs/config-file/.

In particular we may want to use page_rank to rank some content higher, and facetFilters to only search the most recent released version (cf. #669).