doc: tweak search to to understate certain docs

All docs are treated equally in the search results. The built-in search
system knows to emphasize hits in titles and object names, but could use
some help understating hits in non-definitive docs.  In particular, hits
to docs in the  /boards, /samples, and /reference/kconfig docs are often
not as important as hits in other docs, so let's push them later in the
search result output.

We can tweak the search results scoring (and thereby the order of
display) via the ``html_search_scorer`` setting in ``conf.py`` along
with a piece of JavaScript to adjust the result score.

Fixes: #16935

Signed-off-by: David B. Kinder <[email protected]>

doc/conf.py

@@ -277,7 +277,7 @@
 
 # The name of a javascript file (relative to the configuration directory) that
 # implements a search results scorer. If empty, the default will be used.
-#html_search_scorer = 'scorer.js'
+html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'zephyrdoc'

doc/scorer.js

@@ -0,0 +1,48 @@
+/**
+ * Simple search result scoring code.
+ *
+ * Copyright 2007-2018 by the Sphinx team
+ * Copyright (c) 2019, Intel
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+var Scorer = {
+  // Implement the following function to further tweak the score for
+  // each result The function takes a result array [filename, title,
+  // anchor, descr, score] and returns the new score.
+
+  // For Zephyr search results, push display down for kconfig, boards,
+  // and samples so "regular" docs will show up before them
+
+  score: function(result) {
+    if (result[0].search("reference/kconfig/")>=0) {
+       return -5;
+    }
+    else if (result[0].search("boards/")>=0) {
+       return -5;
+    }
+    else if (result[0].search("samples/")>=0) {
+       return -5;
+    }
+    else {
+       return result[4];
+    }
+  },
+
+
+  // query matches the full name of an object
+  objNameMatch: 11,
+  // or matches in the last dotted part of the object name
+  objPartialMatch: 6,
+  // Additive scores depending on the priority of the object
+  objPrio: {0:  15,   // used to be importantResults
+            1:  5,   // used to be objectResults
+            2: -5},  // used to be unimportantResults
+  //  Used when the priority is not in the mapping.
+  objPrioDefault: 0,
+
+  // query found in title
+  title: 15,
+  // query found in terms
+  term: 5
+};