Improve relevance scoring for titles and object-name matches in search results

CHANGES.rst

@@ -92,6 +92,11 @@ Bugs fixed
 * #11961: Omit anchor references from document title entries in the search index,
   removing duplication of search results.
   Patch by James Addison.
+* #12391: Adjust scoring of matches during HTML search so that document main
+  titles tend to rank more highly than subsection titles, and also to provide
+  a gain to matches on the name of programming domain objects relative to
+  title/subtitle matches.
+  Patch by James Addison and Will Lachance.
 
 Testing
 -------

sphinx/themes/basic/static/searchtools.js

@@ -328,13 +328,14 @@ const Search = {
     for (const [title, foundTitles] of Object.entries(allTitles)) {
       if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) {
         for (const [file, id] of foundTitles) {
-          let score = Math.round(100 * queryLower.length / title.length)
+          let score = Math.round(Scorer.title * queryLower.length / title.length);
+          let boost = titles[file] === title ? 1 : 0;  // add a boost for document titles
           normalResults.push([
             docNames[file],
             titles[file] !== title ? `${titles[file]} > ${title}` : title,
             id !== null ? "#" + id : "",
             null,
-            score,
+            score + boost,
             filenames[file],
           ]);
         }

tests/js/roots/titles/conf.py

@@ -0,0 +1,6 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+
+extensions = ['sphinx.ext.autodoc']

tests/js/roots/titles/index.rst

@@ -0,0 +1,20 @@
+Main Page
+=========
+
+This is the main page of the ``titles`` test project.
+
+In particular, this test project is intended to demonstrate how Sphinx
+can handle scoring of query matches against document titles and subsection
+heading titles relative to other document matches such as terms found within
+document text and object names extracted from code.
+
+Relevance
+---------
+
+In the context of search engines, we can say that a document is **relevant**
+to a user's query when it contains information that seems likely to help them
+find an answer to a question they're asking, or to improve their knowledge of
+the subject area they're researching.
+
+.. automodule:: relevance
+   :members:

tests/js/roots/titles/relevance.py

@@ -0,0 +1,4 @@
+class Example:
+    """Example class"""
+    num_attribute = 5
+    text_attribute = "string"

tests/js/roots/titles/relevance.rst

@@ -0,0 +1,13 @@
+Relevance
+=========
+
+In some domains, it can be straightforward to determine whether a search result
+is relevant to the user's query.
+
+For example, if we are in a software programming language domain, and a user
+has issued a query for the term ``printf``, then we could consider a document
+in the corpus that describes a built-in language function with the same name
+as (highly) relevant.  A document that only happens to mention the ``printf``
+function name as part of some example code that appears on the page would
+also be relevant, but likely less relevant than the one that describes the
+function itself in detail.

tests/js/searchtools.js

@@ -7,6 +7,23 @@ describe('Basic html theme search', function() {
       return req.responseText;
   }
 
+  function checkRanking(expectedRanking, results) {
+    let [nextExpected, ...remainingItems] = expectedRanking;
+
+    for (result of results.reverse()) {
+      if (!nextExpected) break;
+
+      let [expectedPage, expectedTitle, expectedTarget] = nextExpected;
+      let [page, title, target] = result;
+
+      if (page == expectedPage && title == expectedTitle && target == expectedTarget) {
+        [nextExpected, ...remainingItems] = remainingItems;
+      }
+    }
+
+    expect(remainingItems.length).toEqual(0);
+  }
+
   describe('terms search', function() {
 
     it('should find "C++" when in index', function() {
@@ -76,7 +93,7 @@ describe('Basic html theme search', function() {
           'Main Page',
           '',
           null,
-          100,
+          16,
           'index.rst'
         ]
       ];
@@ -85,6 +102,38 @@ describe('Basic html theme search', function() {
 
   });
 
+  describe('search result ranking', function() {
+
+    it('should score an object-name match above a page-title match', function() {
+      eval(loadFixture("titles/searchindex.js"));
+
+      expectedRanking = [
+        ['index', 'relevance', '#module-relevance'],  /* py:module documentation */
+        ['relevance', 'Relevance', ''],  /* main title */
+      ];
+
+      searchParameters = Search._parseQuery('relevance');
+      results = Search._performSearch(...searchParameters);
+
+      checkRanking(expectedRanking, results);
+    });
+
+    it('should score an main-title match above a subheading-title match', function() {
+      eval(loadFixture("titles/searchindex.js"));
+
+      expectedRanking = [
+        ['relevance', 'Relevance', ''],  /* main title */
+        ['index', 'Main Page > Relevance', '#relevance'],  /* subsection heading title */
+      ];
+
+      searchParameters = Search._parseQuery('relevance');
+      results = Search._performSearch(...searchParameters);
+
+      checkRanking(expectedRanking, results);
+    });
+
+  });
+
 });
 
 describe("htmlToText", function() {