What effect do the different URL parameters of the Sphinx HTML output's search feature have?

Question

HTML documentation generated by Sphinx includes a search interface.

For example, when searching in the official Python documentation for the term "popen", this URL is constructed:

https://docs.python.org/3/search.html?q=popen&check_keywords=yes&area=default

What effect do the different URL parameters have?

Answer 1

The search execution of Sphinx-generated HTML documentation is completely JavaScript-based and works as follows:

• When you build a Sphinx project, a JavaScript file that contains the search index will be created (searchindex.js).

• When you execute a search query, the search front end will identify all files that are considered a hit and get their source files from the server. These are simple file GET requests that only require a static file server. Snippets of these files that contain the fitting character sequence will be displayed.

Surprisingly, the search algorithm (searchtools.js in the html build in the _static directory) only considers the first (the q) query parameter. All other parameters are ignored.

Note that it is possible to hook up Sphinx to a search back end. For example, the documentation hosting service Read the Docs implements an Haystack/Elasticsearch-based search back end. This means that my explanation does not necessarily apply to all instances of Sphinx-generated documentation sets.