11/*
2- * searchtools.js
3- * ~~~~~~~~~~~~~~~~
4- *
52 * Sphinx JavaScript utilities for the full-text search.
6- *
7- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
8- * :license: BSD, see LICENSE for details.
9- *
103 */
114"use strict" ;
125
@@ -20,7 +13,7 @@ if (typeof Scorer === "undefined") {
2013 // and returns the new score.
2114 /*
2215 score: result => {
23- const [docname, title, anchor, descr, score, filename] = result
16+ const [docname, title, anchor, descr, score, filename, kind ] = result
2417 return score
2518 },
2619 */
@@ -47,6 +40,14 @@ if (typeof Scorer === "undefined") {
4740 } ;
4841}
4942
43+ // Global search result kind enum, used by themes to style search results.
44+ class SearchResultKind {
45+ static get index ( ) { return "index" ; }
46+ static get object ( ) { return "object" ; }
47+ static get text ( ) { return "text" ; }
48+ static get title ( ) { return "title" ; }
49+ }
50+
5051const _removeChildren = ( element ) => {
5152 while ( element && element . lastChild ) element . removeChild ( element . lastChild ) ;
5253} ;
@@ -64,9 +65,13 @@ const _displayItem = (item, searchTerms, highlightTerms) => {
6465 const showSearchSummary = DOCUMENTATION_OPTIONS . SHOW_SEARCH_SUMMARY ;
6566 const contentRoot = document . documentElement . dataset . content_root ;
6667
67- const [ docName , title , anchor , descr , score , _filename ] = item ;
68+ const [ docName , title , anchor , descr , score , _filename , kind ] = item ;
6869
6970 let listItem = document . createElement ( "li" ) ;
71+ // Add a class representing the item's type:
72+ // can be used by a theme's CSS selector for styling
73+ // See SearchResultKind for the class names.
74+ listItem . classList . add ( `kind-${ kind } ) ;
7075 let requestUrl ;
7176 let linkUrl ;
7277 if ( docBuilder === "dirhtml" ) {
@@ -115,8 +120,10 @@ const _finishSearch = (resultCount) => {
115120 "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories."
116121 ) ;
117122 else
118- Search . status . innerText = _ (
119- "Search finished, found ${resultCount} page(s) matching the search query."
123+ Search . status . innerText = Documentation . ngettext (
124+ "Search finished, found one page matching the search query." ,
125+ "Search finished, found ${resultCount} pages matching the search query." ,
126+ resultCount ,
120127 ) . replace ( '${resultCount}' , resultCount ) ;
121128} ;
122129const _displayNextItem = (
@@ -138,7 +145,7 @@ const _displayNextItem = (
138145 else _finishSearch ( resultCount ) ;
139146} ;
140147// Helper function used by query() to order search results.
141- // Each input is an array of [docname, title, anchor, descr, score, filename].
148+ // Each input is an array of [docname, title, anchor, descr, score, filename, kind ].
142149// Order the results by score (in opposite order of appearance, since the
143150// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically.
144151const _orderResultsByScoreThenName = ( a , b ) => {
@@ -248,6 +255,7 @@ const Search = {
248255 searchSummary . classList . add ( "search-summary" ) ;
249256 searchSummary . innerText = "" ;
250257 const searchList = document . createElement ( "ul" ) ;
258+ searchList . setAttribute ( "role" , "list" ) ;
251259 searchList . classList . add ( "search" ) ;
252260
253261 const out = document . getElementById ( "search-results" ) ;
@@ -318,7 +326,7 @@ const Search = {
318326 const indexEntries = Search . _index . indexentries ;
319327
320328 // Collect multiple result groups to be sorted separately and then ordered.
321- // Each is an array of [docname, title, anchor, descr, score, filename].
329+ // Each is an array of [docname, title, anchor, descr, score, filename, kind ].
322330 const normalResults = [ ] ;
323331 const nonMainIndexResults = [ ] ;
324332
@@ -337,6 +345,7 @@ const Search = {
337345 null ,
338346 score + boost ,
339347 filenames [ file ] ,
348+ SearchResultKind . title ,
340349 ] ) ;
341350 }
342351 }
@@ -354,6 +363,7 @@ const Search = {
354363 null ,
355364 score ,
356365 filenames [ file ] ,
366+ SearchResultKind . index ,
357367 ] ;
358368 if ( isMain ) {
359369 normalResults . push ( result ) ;
@@ -475,6 +485,7 @@ const Search = {
475485 descr ,
476486 score ,
477487 filenames [ match [ 0 ] ] ,
488+ SearchResultKind . object ,
478489 ] ) ;
479490 } ;
480491 Object . keys ( objects ) . forEach ( ( prefix ) =>
@@ -502,9 +513,11 @@ const Search = {
502513 // perform the search on the required terms
503514 searchTerms . forEach ( ( word ) => {
504515 const files = [ ] ;
516+ // find documents, if any, containing the query word in their text/title term indices
517+ // use Object.hasOwnProperty to avoid mismatching against prototype properties
505518 const arr = [
506- { files : terms [ word ] , score : Scorer . term } ,
507- { files : titleTerms [ word ] , score : Scorer . title } ,
519+ { files : terms . hasOwnProperty ( word ) ? terms [ word ] : undefined , score : Scorer . term } ,
520+ { files : titleTerms . hasOwnProperty ( word ) ? titleTerms [ word ] : undefined , score : Scorer . title } ,
508521 ] ;
509522 // add support for partial matches
510523 if ( word . length > 2 ) {
@@ -536,8 +549,9 @@ const Search = {
536549
537550 // set score for the word in each file
538551 recordFiles . forEach ( ( file ) => {
539- if ( ! scoreMap . has ( file ) ) scoreMap . set ( file , { } ) ;
540- scoreMap . get ( file ) [ word ] = record . score ;
552+ if ( ! scoreMap . has ( file ) ) scoreMap . set ( file , new Map ( ) ) ;
553+ const fileScores = scoreMap . get ( file ) ;
554+ fileScores . set ( word , record . score ) ;
541555 } ) ;
542556 } ) ;
543557
@@ -576,7 +590,7 @@ const Search = {
576590 break ;
577591
578592 // select one (max) score for the file.
579- const score = Math . max ( ...wordList . map ( ( w ) => scoreMap . get ( file ) [ w ] ) ) ;
593+ const score = Math . max ( ...wordList . map ( ( w ) => scoreMap . get ( file ) . get ( w ) ) ) ;
580594 // add result to the result list
581595 results . push ( [
582596 docNames [ file ] ,
@@ -585,6 +599,7 @@ const Search = {
585599 null ,
586600 score ,
587601 filenames [ file ] ,
602+ SearchResultKind . text ,
588603 ] ) ;
589604 }
590605 return results ;
0 commit comments