8

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?

Braiam
  • 1
  • 11
  • 47
  • 78
theta
  • 24,593
  • 37
  • 119
  • 159

1 Answers1

16

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.

Timotheus.Kampik
  • 2,425
  • 1
  • 22
  • 30
  • Hey, would it be possible to consider also the rest of the results (not just the first one)? e.g. If I have many "keyword" in my search, within the same page, would it be possible to list them all in the search result page? – umbe1987 Dec 14 '17 at 16:24
  • 1
    I don't understand exactly what you mean. The search considers all words you enter and all 'keywords' you define with the corresponding directive. It doesn't consider the additional parameters that are specified (presumably for historic/legacy reasons). In any case, it's possible to define custom Sphinx themes that implement a different search function, based on the search index file Sphinx generates as part of the HTML build. – Timotheus.Kampik Dec 14 '17 at 20:43
  • ok thanks. I misunderstood your answer, now it's clear. Anyway, I guess I might have a look at the other search parameters in the 'searchtools.js' and see if there's something interesting there. – umbe1987 Dec 15 '17 at 21:00