Sphinx Docs | Can it support Algolia's Doc Search

Question

I am wondering if anyone, knows if Algolia's DocSearch Free Service for Docs, can be integrated into a Sphinx Documentation Website. Thank you..

Answer 1

It can definitely be integrated into a Sphinx-Documentation and that quite easily.

I applied for an account and got the API keys.

Read: https://community.algolia.com/docsearch/run-your-own.html

I installed the free docsearch-scraper from github under Python 2.7 and MacOS 10.13 and got it to work using pipenv and an additional post install of the missing dotenv module.

After some fiddling I used a self customized config.json based on the output of the ./docsearch bootstrap command replacing all occurences of "FIXME" in the lines starting with "lvln" with ".section" and replacing "FIXME" in the line starting with "text" with ".document" (see example below).

We successfully indexed the Sphinx-Documentation and running the .docsearch playground command opened a test Webserver that delivered instantly excellent results.

We use the readthedocs sphinx_rtd_theme and you can add the CSS-Links and Javascript snippets from the algolia docs easily in a page.html template extension file created into the _source/_templates/ folder (see below). This folder may be necessary to be registered in the conf.pyof your setup!

Add this to your conf.py at the existing position:

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

and

# 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']

I may come back here with a more detailled step-by-step guide, when I finish the integration.

example config.json:

{
  "index_name": "yourindexname",
  "start_urls": [
    "https://replaceme.com"
  ],
  "stop_urls": [
    "https://replaceme.com/omit"
  ],
  "selectors": {
    "lvl0": ".section h1",
    "lvl1": ".section h2",
    "lvl2": ".section h3",
    "lvl3": ".section h4",
    "lvl4": ".section h5",
    "lvl5": ".section h6",
    "text": ".document p, .document li"
  },
}

more in: https://community.algolia.com/docsearch/config-file.html

This adds the algolia CSS and a custom.css file in the _source/_static/ folder to override styles. Source of the snippets see https://community.algolia.com/docsearch/dropdown.html

example page.html template:

{% extends "!page.html" %}

{% set css_files = css_files + ["https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css", "_static/custom.css"] %}

{% block footer %}
<script
src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script>
docsearch({
  // Your apiKey and indexName will be given to you once
  // we create your config. The appId value is missing in the first 
  // version of this example and in the algolia community doc 
  // until today (5th march of 2019).
  appId: '<your-app-id>',
  apiKey: '<yourkey>',
  indexName: '<yourindex>',
  // 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: true
});
</script>

{% endblock %}

ToDo: Test links to the algolia community documentation

Tipp: You can test if the input selector works by adding this style to your custom.css file:

#rtd-search-form input[type=text]{
    background-color: #c51919; /* red */
}