From 420044b8031ce745de5ffd24a7933683377c1324 Mon Sep 17 00:00:00 2001 From: William Lachance Date: Sun, 4 Feb 2024 16:00:31 -0500 Subject: [PATCH 1/5] HTML Search: Use anchor for search previews --- sphinx/themes/basic/static/searchtools.js | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/sphinx/themes/basic/static/searchtools.js b/sphinx/themes/basic/static/searchtools.js index 8bb1af5a448..c3a43b6c28c 100644 --- a/sphinx/themes/basic/static/searchtools.js +++ b/sphinx/themes/basic/static/searchtools.js @@ -99,7 +99,7 @@ const _displayItem = (item, searchTerms, highlightTerms) => { .then((data) => { if (data) listItem.appendChild( - Search.makeSearchSummary(data, searchTerms) + Search.makeSearchSummary(data, searchTerms, anchor) ); // highlight search terms in the summary if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js @@ -160,10 +160,15 @@ const Search = { _queued_query: null, _pulse_status: -1, - htmlToText: (htmlString) => { + htmlToText: (htmlString, anchor) => { const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() }); - const docContent = htmlElement.querySelector('[role="main"]'); + let docContent = undefined; + if (anchor && htmlElement.querySelector(anchor)) { + docContent = htmlElement.querySelector(anchor); + } else { + docContent = htmlElement.querySelector('[role="main"]'); + } if (docContent) return docContent.textContent; console.warn( "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template." @@ -549,8 +554,8 @@ const Search = { * search summary for a given text. keywords is a list * of stemmed words. */ - makeSearchSummary: (htmlText, keywords) => { - const text = Search.htmlToText(htmlText); + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); if (text === "") return null; const textLower = text.toLowerCase(); From 3bec27621bdaebebe012e17d7ca90635e71b5a30 Mon Sep 17 00:00:00 2001 From: William Lachance Date: Tue, 6 Feb 2024 10:53:31 -0500 Subject: [PATCH 2/5] add test --- tests/js/searchtools.js | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/tests/js/searchtools.js b/tests/js/searchtools.js index c9e0c43d3b2..c4e7685334f 100644 --- a/tests/js/searchtools.js +++ b/tests/js/searchtools.js @@ -31,6 +31,36 @@ describe('Basic html theme search', function() { }); +describe("htmlToText", function() { + it("basic case", () => { + expect(Search.htmlToText(` + +
+
+

Getting Started

+

Some text

+
+
+ `).trim().split(/\s+/)).toEqual(['Getting', 'Started', 'Some', 'text']); + }); + + it("will start reading from the anchor", () => { + expect(Search.htmlToText(` + +
+
+

Getting Started

+

Some text

+
+
+

Other Section

+

Other text

+
+
+ `, '#other-section').trim().split(/\s+/)).toEqual(['Other', 'Section', 'Other', 'text']); + }); +}); + // This is regression test for https://github.com/sphinx-doc/sphinx/issues/3150 describe('splitQuery regression tests', () => { From 292858600eaf7e0d3a5cebe22a7e5606266088e5 Mon Sep 17 00:00:00 2001 From: William Lachance Date: Tue, 6 Feb 2024 11:07:32 -0500 Subject: [PATCH 3/5] Adjust warning to say when anchor content not found --- sphinx/themes/basic/static/searchtools.js | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/sphinx/themes/basic/static/searchtools.js b/sphinx/themes/basic/static/searchtools.js index c3a43b6c28c..e9a43fa5d3e 100644 --- a/sphinx/themes/basic/static/searchtools.js +++ b/sphinx/themes/basic/static/searchtools.js @@ -163,13 +163,19 @@ const Search = { htmlToText: (htmlString, anchor) => { const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() }); - let docContent = undefined; - if (anchor && htmlElement.querySelector(anchor)) { - docContent = htmlElement.querySelector(anchor); - } else { - docContent = htmlElement.querySelector('[role="main"]'); + if (anchor) { + const anchorContent = htmlElement.querySelector(anchor); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchor block not found. Sphinx search tries to obtain it via '${anchor}'. Check your theme or template.` + ); } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); if (docContent) return docContent.textContent; + console.warn( "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template." ); From d64bc0bff6afbc942486ebedf60edcf364e7a5f8 Mon Sep 17 00:00:00 2001 From: William Lachance Date: Tue, 6 Feb 2024 17:25:32 -0500 Subject: [PATCH 4/5] Update test per review comments --- tests/js/searchtools.js | 46 +++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/tests/js/searchtools.js b/tests/js/searchtools.js index c4e7685334f..b70c2d32528 100644 --- a/tests/js/searchtools.js +++ b/tests/js/searchtools.js @@ -32,32 +32,34 @@ describe('Basic html theme search', function() { }); describe("htmlToText", function() { + + const testHTML = ` +
+
+

Getting Started

+

Some text

+
+
+

Other Section

+

Other text

+
+
+

Yet Another Section

+

More text

+
+
+ `; + it("basic case", () => { - expect(Search.htmlToText(` - -
-
-

Getting Started

-

Some text

-
-
- `).trim().split(/\s+/)).toEqual(['Getting', 'Started', 'Some', 'text']); + expect(Search.htmlToText(testHTML).trim().split(/\s+/)).toEqual([ + 'Getting', 'Started', 'Some', 'text', + 'Other', 'Section', 'Other', 'text', + 'Yet', 'Another', 'Section', 'More', 'text' + ]); }); it("will start reading from the anchor", () => { - expect(Search.htmlToText(` - -
-
-

Getting Started

-

Some text

-
-
-

Other Section

-

Other text

-
-
- `, '#other-section').trim().split(/\s+/)).toEqual(['Other', 'Section', 'Other', 'text']); + expect(Search.htmlToText(testHTML, '#other-section').trim().split(/\s+/)).toEqual(['Other', 'Section', 'Other', 'text']); }); }); From 9c5d55f2ba8490fd137a41294f9630acc6d07643 Mon Sep 17 00:00:00 2001 From: William Lachance Date: Tue, 27 Feb 2024 09:11:23 -0500 Subject: [PATCH 5/5] Add changelog entry --- CHANGES.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index f52b9e3d16b..16253c72c59 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -33,6 +33,8 @@ Features added Bugs fixed ---------- +* #11944: Use anchor in search preview. + Patch by Will Lachance. * #11668: Raise a useful error when ``theme.conf`` is missing. Patch by Vinay Sajip. * #11622: Ensure that the order of keys in ``searchindex.js`` is deterministic.