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

CHANGES.rst

@@ -61,6 +61,11 @@ Bugs fixed
 * #12459: Add valid-type arguments to the ``linkcheck_rate_limit_timeout``
   configuration setting.
   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.
 
 Improvements
 ------------

sphinx/themes/basic/static/searchtools.js

@@ -39,6 +39,7 @@ if (typeof Scorer === "undefined") {
     objPrioDefault: 0,
 
     // query found in title
+    mainTitle: 16,
     title: 15,
     partialTitle: 7,
     // query found in terms
@@ -328,7 +329,7 @@ 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((titles[file] !== title ? Scorer.title : Scorer.mainTitle) * queryLower.length / title.length)
           normalResults.push([
             docNames[file],
             titles[file] !== title ? `${titles[file]} > ${title}` : title,

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,21 @@ describe('Basic html theme search', function() {
       return req.responseText;
   }
 
+  function checkRanking(expectedRanking, results) {
+    nextExpected = expectedRanking.pop(0);
+
+    results.forEach(result => {
+      let [expectedPage, expectedTitle, expectedTarget] = nextExpected;
+      let [page, title, target] = result;
+
+      if (page == expectedPage && title == expectedTitle && target == expectedTarget) {
+        nextExpected = expectedRanking.pop(0);
+      }
+    });
+
+    expect(expectedRanking.length).toEqual(0);
+  }
+
   describe('terms search', function() {
 
     it('should find "C++" when in index', function() {
@@ -85,7 +100,7 @@ describe('Basic html theme search', function() {
           'Main Page',
           '#main-page',
           null,
-          100,
+          16,
           'index.rst'
         ]
       ];
@@ -94,6 +109,25 @@ 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', '#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() {