Example: adding Algolia Docsearch to a Sphinx setup that uses 'sphinx_rtd_theme'

[boy-vd]

I'm sorry if this isn't the right place to share, but since I struggled quite a bit with getting Algolia DocSearch to work I thought others might appreciate it as a useful example. I initially wrote and shared this as a reply to an issue on the official Sphinx GitHub repo: sphinx-doc/sphinx#3812.

The following configuration works well for a Sphinx 1.8.5 environment with sphinx_rtd_theme version 0.4.3. It's very easy to implement (basically copy-paste everything to the correct places and make sure to add your own <API_KEY> and <INDEX_NAME>):

# -- Options for HTML output ----------------------------------------------

# Load custom stylesheets to support Algolia search.
html_css_files = [
  'algolia.css',
  'https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css'
]

# Load custom javascript to support Algolia search. Note that the sequence
# defined below (external first) is intentional!
html_js_files = [
  ('https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js', {'defer': 'defer'}),
  ('algolia.js', {'defer': 'defer'})
]

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

The algolia.css file in the _static directory contains the following:

.wy-nav-side { overflow: visible; }
.wy-side-scroll { overflow: inherit; }

And the algolia.js file in the same _static directory contains this:

docsearch({
  apiKey: '<API_KEY>',
  indexName: '<INDEX_NAME>',
  // Replace inputSelector with a CSS selector
  // matching your search input
  inputSelector: '#rtd-search-form input[type=text]',
  // Set debug to true if you want to inspect the dropdown
  debug: false,
  algoliaOptions: {
    hitsPerPage: 8,
  }
});

The above setup makes use of the public crawler that Algolia hosts for free on their servers: https://community.algolia.com/docsearch/dropdown.html. Implementing it based on a crawler that you build yourself shouldn't be much different: https://community.algolia.com/docsearch/run-your-own.html.

[jessetan]

Thanks for your comment, hopefully this will help others in the future.
You could consider turning this into a Sphinx extension if you have the time and knowhow.

I'll close this ticket, since there is nothing left to do but keep it readable for posterity.

[bryevdv]

@boy-vd do you have any thoughts on whether algolia could work on a multi-version site? E.g. we have docs.site.org/en/<version>/ and searches on one version's page should only return results from that same version.

[joleroi]

You can use algolia on multi version sides using facetfilters. This is an example docsearch config that labels the search index entries with a version tag. I have also seen config that solve this problem like this

config = {
        "index_name": "name",
        "start_urls": [
            {
                "url": BASEURL + "(?P<version>.*?)/",
                "variables": {"version": versions},
            }
        ],
        ...

You enable facet filters in the docseach js script like this

<!-- 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: APIKEY,
indexName: INDEXNAME
inputSelector: '### REPLACE ME ####',
algoliaOptions: { 'facetFilters': ["version:$VERSION"] },
debug: false // Set debug to true if you want to inspect the dropdown
});
</script>

[kapooramit]

@boy-vd @joleroi I am exploring https://github.com/algolia/autocomplete to create a instant search with autocomplete which shows matching page names and if possible, API classes, methods, etc. that also show up in toctree if titles_only is false. Any suggestion how can I populate the source?

[sarahpetersen-crypto]

Hi sphinx. I'll be seeing ya. This side of the other.