docs: add advanced search for kernel documentation
Subsystems (2)
PATCH 1/1 docs: add advanced search for kernel documentation
Replace the stock Sphinx search page with one that reuses the existing searchindex.js while adding structured result grouping, filtering, and exact identifier matching.
Results are grouped into Symbols, Sections, Index entries, and Pages, each in a collapsible section with a count. An Advanced panel exposes filters for documentation area, object type, result kind, and exact match mode. All state is URL-encoded so searches remain shareable.
Page summary snippets are lazy-loaded via IntersectionObserver to avoid fetching every matching page up front.
The sidebar keeps the existing quick-search box and adds an "Advanced search" link below it.
--- Documentation/sphinx-static/custom.css | 163 ++++ Documentation/sphinx-static/kernel-search.js | 746 ++++++++++++++++++ Documentation/sphinx/templates/search.html | 106 +++ Documentation/sphinx/templates/searchbox.html | 18 + 4 files changed, 1033 insertions(+) create mode 100644 Documentation/sphinx-static/kernel-search.js create mode 100644 Documentation/sphinx/templates/search.html create mode 100644 Documentation/sphinx/templates/searchbox.html
Documentation/sphinx-static/custom.css +163 -0
@@ -169,3 +169,166 @@ a.manpage { font-weight: bold; font-family: "Courier New", Courier, monospace; } + +/* Keep the quick search box as-is and add a secondary advanced search link. */ +div.sphinxsidebar p.search-advanced-link { + margin: 0.5em 0 0 0; + font-size: 0.95em; +} + +/* + * The enhanced search page keeps the stock GET workflow but adds + * filter controls and grouped results. + */ +form.kernel-search-form { + margin-bottom: 2em; +} + +div.kernel-search-query-row { + display: flex; + flex-wrap: wrap; + gap: 1em; + align-items: end; +} + +div.kernel-search-query-field { + flex: 1 1 26em; +} + +div.kernel-search-query-field label, +div.kernel-search-field label, +fieldset.kernel-search-kind-filters legend { + display: block; + font-weight: bold; + margin-bottom: 0.35em; +} + +div.kernel-search-query-field input[type="text"], +div.kernel-search-field select { + width: 100%; + box-sizing: border-box; +} + +div.kernel-search-query-actions { + display: flex; + align-items: center; + gap: 0.75em; +} + +span.kernel-search-progress { + min-height: 1.2em; + color: #666; +} + +details.kernel-search-advanced { + margin-top: 1em; + padding: 0.75em 1em 1em 1em; + border: 1px solid #cccccc; + background: #f7f7f7; +} + +details.kernel-search-advanced summary { + cursor: pointer; + font-weight: bold; +} + +div.kernel-search-advanced-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(16em, 1fr)); + gap: 1em 1.25em; + margin-top: 1em; +} + +fieldset.kernel-search-kind-filters { + margin: 0; + padding: 0; + border: none; +} + +label.kernel-search-checkbox { + display: flex; + align-items: flex-start; + gap: 0.5em; + margin-bottom: 0.35em; +} + +div.kernel-search-results { + margin-top: 1.5em; +} + +p.kernel-search-status { + margin-bottom: 1.5em; +} + +details.kernel-search-group { + margin-top: 2em; +} + +summary.kernel-search-group-summary { + cursor: pointer; + font-size: 150%; + margin: 0 0 0.6em 0; +} + +summary.kernel-search-group-summary h2.kernel-search-group-title { + display: inline; + margin: 0; + font-size: inherit; + font-weight: normal; +} + +span.kernel-search-group-count { + color: #666666; + margin-left: 0.35em; +} + +ol.kernel-search-list { + list-style: none; + margin: 0; + padding: 0; +} + +li.kernel-search-result { + padding: 0.9em 0; + border-top: 1px solid #dddddd; +} + +li.kernel-search-result:first-child { + border-top: none; +} + +div.kernel-search-result-heading { + font-weight: bold; +} + +div.kernel-search-path, +div.kernel-search-meta, +p.kernel-search-summary { + margin-top: 0.3em; + color: #555555; +} + +div.kernel-search-path, +div.kernel-search-meta { + font-size: 0.95em; +} + +p.kernel-search-summary { + margin-bottom: 0; +} + +@media screen and (max-width: 65em) { + div.kernel-search-query-actions { + width: 100%; + justify-content: flex-start; + } +} + +@media screen and (min-width: 65em) { + div.kernel-search-result-heading, + div.kernel-search-path, + div.kernel-search-meta, + p.kernel-search-summary { + margin-left: 2rem; + } +}
Documentation/sphinx-static/kernel-search.js new file +746 -0
746 lines not on this page · raw message
Documentation/sphinx/templates/search.html new file +106 -0
106 lines not on this page · raw message
Documentation/sphinx/templates/searchbox.html new file +18 -0
@@ -0,0 +1,18 @@ +{# SPDX-License-Identifier: GPL-2.0 #} + +{# Sphinx sidebar template: quick search box plus advanced search link. #} +{%- if pagename != "search" and builder != "singlehtml" %} +<search id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">{{ _('Quick search') }}</h3> + <div class="searchformwrapper"> + <form class="search" action="{{ pathto('search') }}" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="{{ _('Go') }}" /> + </form> + </div> + <p class="search-advanced-link"> + <a href="{{ pathto('search') }}?advanced=1">{{ _('Advanced search') }}</a> + </p> +</search> +<script>document.getElementById('searchbox').style.display = "block"</script> +{%- endif %}
Signature · 1 line
2.51.0
Randy Dunlap
reviewerHi,
Quoted 9 lines · Rito Rhymes
Replace the stock Sphinx search page with one that reuses the existing searchindex.js while adding structured result grouping, filtering, and exact identifier matching.
Results are grouped into Symbols, Sections, Index entries, and Pages, each in a collapsible section with a count. An Advanced panel exposes filters for documentation area, object type, result kind, and exact match mode. All state is URL-encoded so searches remain shareable.
Apparently I need more help/instructions. When I click on Advanced Search and get that web page, I enter "futex" into the Search Query and click on [Search]. I am leaving all Advanced Search options at their default settings.
I get no output. Is this expected?
What am I doing wrong?
thanks.
Quoted 16 lines
Page summary snippets are lazy-loaded via IntersectionObserver to avoid fetching every matching page up front.
The sidebar keeps the existing quick-search box and adds an "Advanced search" link below it.
Signed-off-by Rito Rhymes <[email protected]>--- Documentation/sphinx-static/custom.css | 163 ++++ Documentation/sphinx-static/kernel-search.js | 746 ++++++++++++++++++ Documentation/sphinx/templates/search.html | 106 +++ Documentation/sphinx/templates/searchbox.html | 18 + 4 files changed, 1033 insertions(+) create mode 100644 Documentation/sphinx-static/kernel-search.js create mode 100644 Documentation/sphinx/templates/search.html create mode 100644 Documentation/sphinx/templates/searchbox.html
Signature · 1 line
~Randy
That is not expected.
On my side, searching for "futex" with the default advanced-search settings returns exactly 232 results.
I just tested out reproducing the steps you described on Chrome, Edge and Firefox desktop on Windows and the results were identical across each.
Let's debug here:
Which browser/version are you using? What OS?
Are you running with JavaScript enabled?
Did the browser console show any JavaScript errors?
How did you build the docs? In particular, was this from a fresh rebuild after applying the patch? A stale generated asset or a JS parse/runtime failure could match the behavior you describe.
Rito
Randy Dunlap
reviewerQuoted 5 lines · Rito Rhymes
That is not expected.
On my side, searching for "futex" with the default advanced-search settings returns exactly 232 results.
Quoted 8 lines
I just tested out reproducing the steps you described on Chrome, Edge and Firefox desktop on Windows and the results were identical across each.
Let's debug here:
Which browser/version are you using? What OS?
I tested with chromium-browser and opera.
Chromium: Version 146.0.7680.80 (Official Build) stable@@ (64-bit)
opera: version 121.0.5600.50
Linux v6.19.5 on x86_64.
Quoted 2 lines
Are you running with JavaScript enabled?
Yes.
Quoted 1 line
Did the browser console show any JavaScript errors?
No.
Quoted 3 lines
How did you build the docs? In particular, was this from a fresh rebuild after applying the patch? A stale generated asset or a JS parse/runtime failure could match the behavior you describe.
I removed my previous DOCS build output directory and then did
$ make O=DOCS htmldocs
Signature · 1 line
~Randy
I was using the in-tree build (make htmldocs) before. I just ran fresh rebuilds with both in-tree and out-of-tree (make O=DOCS htmldocs) builds, and I got identical search results of 280 hits for "futex" when serving both.
I ran the builds and served the output on Linux/x86_64, and tested the pages in Chrome, Edge, and Firefox on Windows.
So at this point I have not been able to reproduce the "no output" behavior with either build mode, I think we can rule out build mode quirks.
More debugging:
As a comparison, WITHOUT using my patch, upstream only build, does the normal Quick Search work? What results do you get for Futex?
WITH my patch, do Quick Search return any results for Futex?
How are you opening or serving the generated docs? For example, via a local web server (http://...) or directly from disk (file://...)? I am serving the generated output over HTTP locally via python -m http.server.
What Sphinx version are you using for the build?
I built with Sphinx 9.1.0.
If possible, could you also check in the browser network tab whether _static/kernel-search.js, _static/language_data.js, and searchindex.js are all loading successfully?
Randy Dunlap
reviewerQuoted 8 lines · Rito Rhymes
I was using the in-tree build (
make htmldocs) before. I just ran fresh rebuilds with both in-tree and out-of-tree (make O=DOCS htmldocs) builds, and I got identical search results of 280 hits for "futex" when serving both.I ran the builds and served the output on Linux/x86_64, and tested the pages in Chrome, Edge, and Firefox on Windows.
Quoted 8 lines
So at this point I have not been able to reproduce the "no output" behavior with either build mode, I think we can rule out build mode quirks.
More debugging:
As a comparison, WITHOUT using my patch, upstream only build, does the normal Quick Search work? What results do you get for Futex?
Yes:
Search Results
Search finished, found 225 pages matching the search query.
Quoted 1 line
WITH my patch, do Quick Search return any results for Futex?
No. Just a search dialog page with no matches listed.
Quoted 4 lines
How are you opening or serving the generated docs? For example, via a local web server (
http://...) or directly from disk (file://...)? I am serving the generated output over HTTP locally viapython -m http.server.
file://...
Quoted 2 lines
What Sphinx version are you using for the build?
I built with Sphinx 9.1.0.
8.2.3-4.2 (latest from openSUSE Tumbleweed, rolling updates)
Quoted 3 lines
If possible, could you also check in the browser network tab whether
_static/kernel-search.js,_static/language_data.js, andsearchindex.jsare all loading successfully?
They appear to be (this is new to me).
They are listed and I don't see any errors associated with them.
Signature · 1 line
~Randy
I believe I identified the issue as a Sphinx version compatibility problem.
I've been working on a more robust reroll. I expect to have it by tomorrow, and we can test it when you're ready.
Rito
Randy Dunlap
reviewerQuoted 5 lines · Rito Rhymes
I believe I identified the issue as a Sphinx version compatibility problem.
I've been working on a more robust reroll. I expect to have it by tomorrow, and we can test it when you're ready.
Sounds good. Thanks.
Signature · 1 line
~Randy
I'm still working on the advanced search reroll. It's turned into a more substantial update than I first expected.
Rito
Jonathan Corbet
maintainerQuoted 17 lines · Rito Rhymes
Replace the stock Sphinx search page with one that reuses the existing searchindex.js while adding structured result grouping, filtering, and exact identifier matching.
Results are grouped into Symbols, Sections, Index entries, and Pages, each in a collapsible section with a count. An Advanced panel exposes filters for documentation area, object type, result kind, and exact match mode. All state is URL-encoded so searches remain shareable.
Page summary snippets are lazy-loaded via IntersectionObserver to avoid fetching every matching page up front.
The sidebar keeps the existing quick-search box and adds an "Advanced search" link below it.
Signed-off-by Rito Rhymes <[email protected]>
Quoted 9 lines
--- Documentation/sphinx-static/custom.css | 163 ++++ Documentation/sphinx-static/kernel-search.js | 746 ++++++++++++++++++ Documentation/sphinx/templates/search.html | 106 +++ Documentation/sphinx/templates/searchbox.html | 18 + 4 files changed, 1033 insertions(+) create mode 100644 Documentation/sphinx-static/kernel-search.js create mode 100644 Documentation/sphinx/templates/search.html create mode 100644 Documentation/sphinx/templates/searchbox.html
Without looking into detail at the work (yet), can you tell me something about how this work was created? We do have guidance for the disclosure of the use of coding tools in Documentation/process/coding-assistants.rst ...
I'm curious about where you are going with this in general. A look at ritovision.com does not suggest "kernel developer" to me.
Thanks,
jon
Hi Jon
Quoted 1 line
Documentation/process/coding-assistants.rst
That was my oversight. I failed to include the appropriate coding-assistant attribution/disclosure, and I will reroll my patches accordingly.
Quoted 1 line
I'm curious about where you are going with this in general
I am not contributing as a kernel developer. My background is in front-end engineering, product/UX, and developer-facing documentation and platform surfaces, and that is where I believe I can add value here.
Linux is important infrastructure, and I have already been making related contributions in its ecosystem. In trying to improve lore.kernel.org, I contributed patches merged upstream to Public Inbox for small-screen layout behavior and for enabling admin-injected meta tags in the document head.
After my Git patches for gitweb mobile responsiveness were merged, I prepared a kernel.org mobile-responsiveness patch series (current theme is only built for desktop and breaks on small screens). Since there was not an established mailing-list path for merging that work, Johannes Schindelin introduced me to Konstantin in an archived thread, which opened a concrete path for contributing to kernel.org.
More broadly, I have worked on improving developer-facing surfaces, including documentation and related tooling, in other OSS projects. That is the kind of value I am aiming to add here: not direct kernel development, but improving usability, discoverability, and developer experience around important technical infrastructure.
Rito
Also for reference, I have twice implemented an advanced search feature for the OWASP Vulnerable Web Applications Directory (VWAD): first for an earlier version of the site, and more recently for its newly launched current version.
The kernel documentation search work here is a different system with a different purpose, but it is adjacent experience, and I would appreciate any feedback you or others may have on improving the patch.
Rito
Jonathan Corbet
maintainerQuoted 7 lines · Rito Rhymes
Hi Jon
Quoted 1 line
Documentation/process/coding-assistants.rstThat was my oversight. I failed to include the appropriate coding-assistant attribution/disclosure, and I will reroll my patches accordingly.
That's a good step in the right direction.
Quoted 5 lines
Quoted 1 line
I'm curious about where you are going with this in general
I am not contributing as a kernel developer. My background is in front-end engineering, product/UX, and developer-facing documentation and platform surfaces, and that is where I believe I can add value here.
The reason I ask is that submissions to the kernel - even those for the documentation - have to be evaluated with an eye toward ongoing maintenance. A couple of lines of CSS tweak are easily accepted. 1,000 lines of uncommented Javascript, CSS, and Jinja -- none of which fall in the core strengths of most kernel developers -- have to be looked at more carefully.
Who is going to maintain this code going forward? How well do you truly understand this code, which you did not write yourself? Will you be there to help resolve problems that show up in six months or a year?
Quoted 5 lines
Linux is important infrastructure, and I have already been making related contributions in its ecosystem. In trying to improve lore.kernel.org, I contributed patches merged upstream to Public Inbox for small-screen layout behavior and for enabling admin-injected meta tags in the document head.
You did get a few patches past Eric, that says something :)
Quoted 5 lines
More broadly, I have worked on improving developer-facing surfaces, including documentation and related tooling, in other OSS projects. That is the kind of value I am aiming to add here: not direct kernel development, but improving usability, discoverability, and developer experience around important technical infrastructure.
Worthy goals, certainly.
For the moment I'll ask you to slow down a bit; there are real humans on the receiving side of these patches who have to deal with them. I'll get there shortly, but you're not the only thing in the queue. The simple changes seem generally OK from a first quick glance.
I am far from convinced about this particular patch, though. Before I accept code that will run in the browser of everybody who reads the rendered kernel docs, I need to understand that code well, and the current posting is not entirely amenable to that.
Thanks,
jon
PATCH v2 1/1 docs: add advanced search for kernel documentation
In reply to Rito RhymesReplace the stock Sphinx search page with one that reuses the existing searchindex.js while adding structured result grouping, filtering, and exact identifier matching.
Results are grouped into Symbols, Sections, Index entries, and Pages, each in a collapsible section with a count. An Advanced panel exposes filters for documentation area, object type, result kind, and exact match mode. All state is URL-encoded so searches remain shareable.
Page summary snippets are lazy-loaded via IntersectionObserver to avoid fetching every matching page up front.
The sidebar keeps the existing quick-search box and adds an "Advanced search" link below it.
---
v2: add Assisted-by attribution
Documentation/sphinx-static/custom.css | 163 ++++ Documentation/sphinx-static/kernel-search.js | 746 ++++++++++++++++++ Documentation/sphinx/templates/search.html | 106 +++ Documentation/sphinx/templates/searchbox.html | 18 + 4 files changed, 1033 insertions(+) create mode 100644 Documentation/sphinx-static/kernel-search.js create mode 100644 Documentation/sphinx/templates/search.html create mode 100644 Documentation/sphinx/templates/searchbox.html
Documentation/sphinx-static/custom.css +163 -0
@@ -169,3 +169,166 @@ a.manpage { font-weight: bold; font-family: "Courier New", Courier, monospace; } + +/* Keep the quick search box as-is and add a secondary advanced search link. */ +div.sphinxsidebar p.search-advanced-link { + margin: 0.5em 0 0 0; + font-size: 0.95em; +} + +/* + * The enhanced search page keeps the stock GET workflow but adds + * filter controls and grouped results. + */ +form.kernel-search-form { + margin-bottom: 2em; +} + +div.kernel-search-query-row { + display: flex; + flex-wrap: wrap; + gap: 1em; + align-items: end; +} + +div.kernel-search-query-field { + flex: 1 1 26em; +} + +div.kernel-search-query-field label, +div.kernel-search-field label, +fieldset.kernel-search-kind-filters legend { + display: block; + font-weight: bold; + margin-bottom: 0.35em; +} + +div.kernel-search-query-field input[type="text"], +div.kernel-search-field select { + width: 100%; + box-sizing: border-box; +} + +div.kernel-search-query-actions { + display: flex; + align-items: center; + gap: 0.75em; +} + +span.kernel-search-progress { + min-height: 1.2em; + color: #666; +} + +details.kernel-search-advanced { + margin-top: 1em; + padding: 0.75em 1em 1em 1em; + border: 1px solid #cccccc; + background: #f7f7f7; +} + +details.kernel-search-advanced summary { + cursor: pointer; + font-weight: bold; +} + +div.kernel-search-advanced-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(16em, 1fr)); + gap: 1em 1.25em; + margin-top: 1em; +} + +fieldset.kernel-search-kind-filters { + margin: 0; + padding: 0; + border: none; +} + +label.kernel-search-checkbox { + display: flex; + align-items: flex-start; + gap: 0.5em; + margin-bottom: 0.35em; +} + +div.kernel-search-results { + margin-top: 1.5em; +} + +p.kernel-search-status { + margin-bottom: 1.5em; +} + +details.kernel-search-group { + margin-top: 2em; +} + +summary.kernel-search-group-summary { + cursor: pointer; + font-size: 150%; + margin: 0 0 0.6em 0; +} + +summary.kernel-search-group-summary h2.kernel-search-group-title { + display: inline; + margin: 0; + font-size: inherit; + font-weight: normal; +} + +span.kernel-search-group-count { + color: #666666; + margin-left: 0.35em; +} + +ol.kernel-search-list { + list-style: none; + margin: 0; + padding: 0; +} + +li.kernel-search-result { + padding: 0.9em 0; + border-top: 1px solid #dddddd; +} + +li.kernel-search-result:first-child { + border-top: none; +} + +div.kernel-search-result-heading { + font-weight: bold; +} + +div.kernel-search-path, +div.kernel-search-meta, +p.kernel-search-summary { + margin-top: 0.3em; + color: #555555; +} + +div.kernel-search-path, +div.kernel-search-meta { + font-size: 0.95em; +} + +p.kernel-search-summary { + margin-bottom: 0; +} + +@media screen and (max-width: 65em) { + div.kernel-search-query-actions { + width: 100%; + justify-content: flex-start; + } +} + +@media screen and (min-width: 65em) { + div.kernel-search-result-heading, + div.kernel-search-path, + div.kernel-search-meta, + p.kernel-search-summary { + margin-left: 2rem; + } +}
Documentation/sphinx-static/kernel-search.js new file +746 -0
746 lines not on this page · raw message
Documentation/sphinx/templates/search.html new file +106 -0
106 lines not on this page · raw message
Documentation/sphinx/templates/searchbox.html new file +18 -0
@@ -0,0 +1,18 @@ +{# SPDX-License-Identifier: GPL-2.0 #} + +{# Sphinx sidebar template: quick search box plus advanced search link. #} +{%- if pagename != "search" and builder != "singlehtml" %} +<search id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">{{ _('Quick search') }}</h3> + <div class="searchformwrapper"> + <form class="search" action="{{ pathto('search') }}" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="{{ _('Go') }}" /> + </form> + </div> + <p class="search-advanced-link"> + <a href="{{ pathto('search') }}?advanced=1">{{ _('Advanced search') }}</a> + </p> +</search> +<script>document.getElementById('searchbox').style.display = "block"</script> +{%- endif %}
Signature · 1 line
2.51.0
v3 cover docs: advanced search with benchmark harness
In reply to Rito RhymesThis series adds an Advanced Search interface for kernel documentation.
This is being proposed here rather than upstream Sphinx because the current implementation is tailored to the kernel documentation set and its navigation needs, and is integrated through kernel-local template and static-asset overrides rather than a generalized Sphinx extension interface.
Parts of the approach could potentially be abstracted further in the future, but this series is focused on solving the problem concretely for kernel documentation first rather than proposing a general-purpose Sphinx search redesign.
The first patch adds the feature itself: an advanced search page built on the existing Sphinx search data, with tabbed results for Symbols, Sections, Index entries, and Pages, richer filtering, more targeted identifier search, and bounded Pages summary loading with compatibility handling across supported Sphinx versions.
The second patch adds optional developer-side benchmark tooling and passive timing instrumentation used to validate runtime behavior and compare advanced search with stock Quick Search.
Jon previously noted that the window for larger merges has passed, so this is not intended as a request to take a large feature late in the current cycle. The immediate goal is to close the loop on the debugging and compatibility work around the earlier version, so the current implementation is available for testing and review ahead of future merge windows.
This version should address the compatibility issue Randy had reported with the earlier implementation. If Randy has time to try this updated version with the setup that exposed the earlier problem, I would appreciate confirmation that it now behaves correctly there.
Rito Rhymes (2):
docs: add advanced search for kernel documentation
docs: add advanced search benchmark harness and instrumentation
Documentation/doc-guide/sphinx.rst | 100 ++ Documentation/sphinx-static/custom.css | 288 ++++ Documentation/sphinx-static/kernel-search.js | 1264 ++++++++++++++++ Documentation/sphinx/templates/search.html | 117 ++ Documentation/sphinx/templates/searchbox.html | 30 + MAINTAINERS | 11 + tools/docs/bench_search_playwright.mjs | 1278 +++++++++++++++++ tools/docs/test_advanced_search.py | 312 ++++ 8 files changed, 3400 insertions(+) create mode 100644 Documentation/sphinx-static/kernel-search.js create mode 100644 Documentation/sphinx/templates/search.html create mode 100644 Documentation/sphinx/templates/searchbox.html create mode 100755 tools/docs/bench_search_playwright.mjs create mode 100755 tools/docs/test_advanced_search.py
Signature · 1 line
2.51.0
PATCH v3 1/2 docs: add advanced search for kernel documentation
Replace the stock search page with a kernel-specific search UI that still builds on Sphinx-generated search data.
Results are grouped into Symbols, Sections, Index entries, and Pages. The advanced panel adds filters for documentation area, object type, result kind, and exact identifier matching while preserving shareable URL state. Result kinds are presented as tabs so broad searches can switch between them without scrolling through large sections.
Page summaries are fetched only for the Pages result kind. The default view limits summaries to the first 50 page results while allowing a per-session opt-out for deeper summary loading. Summary loading is deferred to the active Pages view, and stale work is canceled when the query or active result kind changes.
The sidebar search template is replaced with a matching quick-search entry point that links to the advanced search page.
The runtime includes compatibility handling for the supported Sphinx range, including older search-index layouts and pre-9.x stopword APIs. On Sphinx 3.4.3 through 5.1.x, advanced search degrades gracefully to Symbols and Pages because those versions do not emit the section and index metadata available in 5.2.0 and newer.
A lightweight build-time smoke test is included for the generated search page, copied runtime asset, and search-index contract.
---
Summary
=======
This feature adds an Advanced Search interface for kernel documentation. It is intended to provide a more capable complement to regex and grep than the existing Quick Search interface, while still building on the same underlying Sphinx search primitives.
It organizes results into Symbols, Sections, Index entries, and Pages, while also exposing filters and more targeted identifier search.
The implementation stays close to the existing Sphinx search model. It reuses existing Sphinx-generated search artifacts and adds a client-side interface around them, rather than introducing a separate indexing pipeline, non-Sphinx search backend, or additional build-time infrastructure.
It is intended to remain broadly compatible with supported Sphinx builds and to work with both in-tree and out-of-tree documentation builds.
It also changes the runtime cost shape of documentation search. In the default view, advanced search renders grouped results without triggering page-summary fetches, and in limited Pages mode it loads only the rendered page summaries, up to 50. On broader queries, that substantially reduces request volume and transferred bytes compared with the stock Quick Search page.
Problem and Purpose
===================
The need for this feature can be understood through this context sequence:
1. Kernel contributors and documentation readers need to navigate a very large body of material spread across many subsystems, APIs, generated reference pages, and long-form documents, often without already knowing which page contains the thing they need.
2. Regex and grep are powerful for precise text hunting in a local source tree, but they are not ideal for finding the right rendered documentation page, section, or symbol when the user does not already know where to look.
3. The existing quick search provides a useful lightweight entry point, but it does not expose richer filtering, result grouping, or more targeted identifier search workflows. On broader queries, it also scales page-summary loading work with result breadth, which makes the experience both noisier and more resource-intensive than it needs to be.
4. Maintenance of complex front-end systems is a higher barrier in this environment because there are fewer contributors focused on front-end implementation details. For that reason, safer solutions should stay within the existing documentation infrastructure rather than introducing additional dependencies or separate supporting systems.
Taken together, these constraints favor a solution that improves navigation within rendered documentation while remaining within the existing documentation infrastructure and search model.
Design Goals
============
- Expose more structured search workflows than Quick Search.
- Keep the implementation aligned with established documentation architecture to limit maintenance and onboarding overhead.
- Remain easy to disable or roll back if needed.
- Allow for future filter adjustment or expansion without restructuring the system.
- Use standard HTML form semantics rather than custom widget frameworks.
- Keyboard navigation and standard accessible form semantics with no custom focus management.
- Maintain broad Sphinx version compatibility.
- Work with both in-tree and out-of-tree documentation builds.
Anti-goals
==========
- Replacing regex or grep.
- Introducing a separate search backend.
- Adding new build-time dependencies.
- Altering build-time processes
- Adding low-value bells and whistles that increase complexity.
- Redesigning the theme.
- Redesigning the sidebar search.
Design & Implementation
=======================
Architecture Overview
---------------------
This feature is implemented by extending the Sphinx documentation setup already used by the kernel tree, rather than by introducing a separate search backend or indexing pipeline.
Sphinx already provides several useful extension points for this kind of feature. It allows template overrides through the configured template path, static asset overrides through the configured static path, and it generates search artifacts such as searchindex.js and language_data.js as part of the normal documentation build.
Those existing hooks define the basic boundaries of the implementation. The feature can replace or extend the rendered search UI, add client-side behavior, and reuse Sphinx-generated search data, but it does not create its own independent search index or separate documentation build system.
Baseline Search Structure
-------------------------
The default Sphinx setup already provides a basic quick-search entry point and the generated search artifacts needed for client-side searching.
In the kernel documentation build, this means the existing setup already exposes:
* a sidebar quick-search box
* a generated searchindex.js file
* generated language_data.js search-language support
* the stock Sphinx search page and initialization model
What it does not provide is a richer search workflow tailored to kernel documentation navigation. In particular, the default flow does not provide grouped results, richer filtering, or a dedicated search interface for navigating symbols, sections, index entries, and pages as distinct result kinds.
Template Integration
--------------------
The feature is integrated through two Sphinx template overrides:
* Documentation/sphinx/templates/searchbox.html
* Documentation/sphinx/templates/search.html
searchbox.html serves as the sidebar entry point. It is effectively a close copy of the theme's default quick-search component, but adds a dedicated link to search.html?advanced=1 so the full search page opens with the advanced filters enabled.
search.html provides the full Advanced Search page. It defines the search query field, the advanced filter controls, and the results container that is later populated by Documentation/sphinx-static/kernel-search.js.
The feature is also trivial to rollback. Because the integration is implemented as template overrides, rollback only requires deleting searchbox.html and search.html. That restores the original default Sphinx theme templates (including Quick Search) without untangling architecture, altering configuration, or reverting history.
User Interface and Styling
--------------------------
The user-facing interface is defined in search.html and styled in Documentation/sphinx-static/custom.css.
The markup in search.html is a shared contract with kernel-search.js and custom.css. The JavaScript runtime depends on specific form IDs and result container IDs, while the CSS depends on the corresponding classes. Changes to the template markup therefore need to be made with both files in mind.
At a high level, the page provides:
* a search query field
* a submit action and progress/status area
* a collapsible advanced-filter panel
* result-kind filters
* documentation-area and object-type filters
* a runtime-rendered tabbed results interface
* a Pages summary-loading mode toggle
That runtime-rendered results interface is built by kernel-search.js. It renders result tabs for Symbols, Sections, Index entries, and Pages, along with per-kind result panels. The Pages tab includes its own summary-loading mode control so the user can switch between the normal limited mode and a broader unbounded mode directly within that view when needed.
The CSS in custom.css is responsible for the layout and responsive presentation of the search interface. In particular, it supports the tabbed results UI and keeps the result tabs sticky so users can switch between result kinds at any time while searching, even when the result lists are long.
The templates use standard accessible form semantics, including labeled controls, grouped filter fields, and a collapsible advanced-filter panel.
JavaScript Runtime Flow
-----------------------
The client-side runtime is implemented inDocumentation/sphinx-static/kernel-search.js.
At a high level, the flow is:
1. search.html includes _static/language_data.js, kernel-search.js, and the generated searchindex.js.
2. kernel-search.js waits for searchindex.js to populate the shared Search index.
3. The runtime reads query state from the page and URL parameters.
4. The query is normalized and prepared for matching.
5. The runtime searches across Sphinx-generated index structures and collects matches as distinct result kinds: Symbols, Sections, Index entries, and Pages.
6. The collected matches are scored, grouped, filtered, and rendered into the results container in search.html.
7. For page results, summaries may be fetched lazily from generated HTML pages after the initial result set is rendered.
Page Summaries and Runtime Cost
-------------------------------
The most important runtime distinction from the stock search page is how page summaries are loaded.
In the default advanced-search view, grouped results are rendered without triggering page-summary fetches. Page summaries are fetched only when the user switches to the Pages tab.
In that Pages view, the normal mode is intentionally limited. It loads only the rendered page summaries, up to a maximum of 50. For smaller queries, that means loading all rendered page summaries when fewer than 50 exist. For broader queries, that keeps page-summary work bounded instead of scaling with the full result set.
This means the feature does not remove the shared Sphinx startup and search-index load cost. The main runtime change happens after initial results are available: the advanced interface reduces the amount of follow-on summary-loading work, especially for broader queries.
Extensibility
-------------
The current structure is intended to support incremental changes within the existing search model.
In practice, that means it is straightforward to:
- add or adjust filters in ``search.html``
- add corresponding styling in ``custom.css``
- extend query handling and result collection in ``kernel-search.js``
- tune ranking and grouping behavior within the existing client-side runtime
This makes the feature reasonably extensible for incremental search UI and result-model improvements, while still keeping the implementation contained within the existing Sphinx template and static-asset model.
Sphinx Version Compatibility
----------------------------
Sphinx version compatibility is handled in kernel-search.js by accounting for the meaningful differences in generated search data across supported versions.
The main compatibility differences are:
* stopword representation
* object index layout
* availability of section and index-entry metadata
Sphinx 3.4.3 through 8.2.3 expose stopwords in a form that behaves like an array. Sphinx 9.1.0 exposes stopwords in a form that behaves like a set. The runtime includes compatibility handling for both representations.
The generated object index also differs across versions. Sphinx 3.4.3 uses a name-to-tuple mapping for object entries, while Sphinx 4.0 and newer use an array-based layout. The runtime supports both forms when collecting Symbol results.
The most visible functional difference is that Sphinx 3.4.3 through 5.1.x do not emit the alltitles and indexentries metadata used to populate Sections and Index entries. Because of that, that range provides partial support: Symbols and Pages still work, but expect fewer total results because Sections and Index entries are unavailable.
Sphinx 5.2.x and newer provide full support.
Compatibility
=============
This feature works with both in-tree and out-of-tree documentation builds.
The interface requires JavaScript at runtime.
Sphinx 5.2 and newer provide full support.
Sphinx 3.4.3 through 5.1.x provide partial support. In that range, the feature remains usable, but older Sphinx builds do not emit the metadata needed for Sections and Index entries. As a result, expect fewer total results, with only Symbols and Pages available.
This behavior was directly validated on:
- Sphinx 9.1.0
- Sphinx 8.2.3
- Sphinx 3.4.3 on Python 3.9
For example, searching for futex under full support returns 280 results. On Sphinx 3.4.3, the same search returns 223 results: 200 Symbols and 23 Pages, with no Sections or Index entries.
This runtime behavior was benchmarked on Sphinx 9.1.0 against stock Quick Search using the queries kernel, futex, and landlock. Across that set, advanced search kept the default path flat at zero page-summary requests and 12 total requests, while stock summary work grew with query breadth. In limited Pages mode, advanced search loaded 10 page summaries for landlock, 23 for futex, and 50 for kernel.
Trade-offs
==========
This feature accepts some additional template, CSS, and JavaScript complexity in exchange for a more structured and useful search workflow than the existing Quick Search interface can provide.
At the same time, it avoids a much larger architectural jump. Rather than introducing a separate indexing pipeline, non-Sphinx backend, or additional build-time infrastructure, it stays within the existing Sphinx search model and reuses Sphinx-generated search artifacts.
That design keeps the feature more contained, easier to integrate, and trivial to rollback, but it also means the feature remains bounded by the data that Sphinx already emits.
One explicit compatibility trade-off is that Sphinx 3.4.3 through 5.1.x provide only partial support. Supporting those versions fully would require additional compatibility logic for metadata they do not emit. Instead, the feature accepts degraded results in that range while keeping full support on newer Sphinx versions.
This is not a universal first-summary latency win. On broad queries such as kernel, the stock search page can reach a first resolved summary sooner, but it does so by issuing far more requests and transferring far more data. The performance advantage of advanced search is that it reduces summary-loading work and keeps that work bounded as query breadth increases.
So the overall trade-off shape is:
- more capability than Quick Search, but more complexity to maintain
- less complexity than a separate search architecture, and lower maintenance and learning overhead because it stays within the existing Sphinx infrastructure.
- broad support across Sphinx versions, but not uniform support on earlier versions to avoid greater maintenance complexity.
- another subsystem to maintain, but trivial to rollback if needed.
Maintenance and Risk Considerations
===================================
The main maintenance burden comes from the fact that this feature is a coordinated template/CSS/JavaScript unit rather than a single isolated change. search.html, searchbox.html, custom.css, and kernel-search.js depend on a shared contract of markup structure, IDs, and classes. Changes in one of those files may require corresponding changes in the others.
A second maintenance risk is Sphinx-version drift. The feature relies on Sphinx-generated search data and therefore depends on the structure and availability of that data remaining compatible enough for the runtime to interpret it correctly. The main known variation points are stopword representation, object index layout, and metadata availability for Sections and Index entries. Future Sphinx releases may require renewed validation or additional compatibility handling.
The feature also depends on generated HTML structure when deriving page summaries. If the relevant page markup changes, summary extraction may degrade even if the underlying search index still works correctly. That makes summary behavior one of the more fragile parts of the runtime.
Theme and layout changes are another practical risk. The feature is integrated through kernel-local template overrides and styling, so changes to surrounding layout expectations may require corresponding adjustments to searchbox integration, page structure, or responsive presentation.
These risks are mitigated by keeping the feature within the existing Sphinx extension points, avoiding new build-time dependencies or a separate search backend, validating behavior across supported Sphinx versions with the smoke test in tools/docs/test_advanced_search.py and the developer-side benchmark harness in tools/docs/bench_search_playwright.mjs, and keeping rollback simple through removal of the template overrides and static assets. The benchmark harness is a developer tool for validation and comparison, not a dependency of the documentation build itself.
v3:
- Reworked the results UI from collapsible groups to a tabbed interface.
- Added sticky result tabs so result-kind switching remains available while browsing long result lists.
- Added a Pages summary-loading mode control to the Pages view.
- Hardened Pages summary loading so it starts only when the Pages view is opened, reuses fetched page text within the page session, applies bounded concurrent loading, and supports a limited mode that caps rendered page summaries at 50.
- Clarified and expanded Sphinx compatibility handling, including graceful degraded behavior on older builds.
- Added a build-time smoke test for advanced-search assets and search page wiring.
- Added integration, compatibility, testing, and rollback documentation.
- Added a MAINTAINERS entry for the main feature file.
Documentation/doc-guide/sphinx.rst | 71 + Documentation/sphinx-static/custom.css | 288 ++++ Documentation/sphinx-static/kernel-search.js | 1182 +++++++++++++++++ Documentation/sphinx/templates/search.html | 117 ++ Documentation/sphinx/templates/searchbox.html | 30 + MAINTAINERS | 10 + tools/docs/test_advanced_search.py | 312 +++++ 7 files changed, 2010 insertions(+) create mode 100644 Documentation/sphinx-static/kernel-search.js create mode 100644 Documentation/sphinx/templates/search.html create mode 100644 Documentation/sphinx/templates/searchbox.html create mode 100755 tools/docs/test_advanced_search.py
Documentation/doc-guide/sphinx.rst +71 -0
@@ -194,6 +194,77 @@ subdirectories you can specify. To remove the generated documentation, run ``make cleandocs``. +Advanced Search Integration +--------------------------- + +The advanced search integration is a kernel-specific Sphinx +customization that overrides the stock search page and sidebar +quick-search template to provide a more capable search interface for +kernel documentation while still building on the same underlying +Sphinx search primitives. + +The advanced search integration is implemented by three files: + +* ``Documentation/sphinx/templates/search.html`` for the custom search page; +* ``Documentation/sphinx/templates/searchbox.html`` for the sidebar link; +* ``Documentation/sphinx-static/kernel-search.js`` for the client-side + search runtime. + +The page relies on a strict boot order. ``language_data.js`` must load +before ``kernel-search.js``, and ``searchindex.js`` must load afterwards +to populate the shared search index consumed by the runtime. + +The runtime works with all supported Sphinx versions, but the available +result kinds differ by the metadata present in ``searchindex.js``: + +* Sphinx ``3.4.3`` through ``5.1.x`` provide ``Symbols`` and ``Pages``. + ``Sections`` and ``Index entries`` are unavailable because those + versions do not emit the ``alltitles`` and ``indexentries`` fields. +* Sphinx ``5.2.0`` and newer provide the full result set: ``Symbols``, + ``Sections``, ``Index entries``, and ``Pages``. + +Runtime behavior is intentionally bounded, but still fully client-side: + +* ``searchindex.js`` is loaded into the browser before any query can run, + and broad full-site builds can still increase page-load and query latency. +* The ``Pages`` group starts collapsed. Page-summary fetches begin only + after the user opens that group. +* Page summaries are fetched on demand after the user opens the + ``Pages`` group. Browsers with ``IntersectionObserver`` keep that work + near the viewport, with at most four concurrent requests, an + eight-second timeout, and a limit of fifty summarized page results per + query. +* Successful summary fetches are cached for the current page session. + Aborted or failed fetches are not cached, and the result remains usable + as a normal link even when its summary is unavailable. + +If full-site ``searchindex.js`` size becomes the bottleneck, that needs a +larger follow-up design such as precomputed summary sidecars, sharded +search data, or a server-backed search service. The client-side runtime +described here does not solve that class of scaling limit. + +For a quick local regression check, run:: + + python3 tools/docs/test_advanced_search.py + +It builds a small documentation subset and verifies the generated search +page, copied static assets, and the search index contract used by the +client-side search runtime. + +To verify full-site support for a change, also run at least one full +``make htmldocs`` build and manually exercise the generated ``search.html`` +page. + +To disable the feature and return to the theme's default Quick Search setup, +remove the two template overrides: + +* ``Documentation/sphinx/templates/search.html`` +* ``Documentation/sphinx/templates/searchbox.html`` + +That restores the native Sphinx search page and the default sidebar quick +search box. ``kernel-search.js`` can then be removed as follow-up cleanup, +but removing the two template overrides is enough to roll back behavior. + .. [#ink] Having ``inkscape(1)`` from Inkscape (https://inkscape.org) as well would improve the quality of images embedded in PDF documents, especially for kernel releases 5.18 and later.
Documentation/sphinx-static/custom.css +288 -0
291 lines not on this page · raw message
Documentation/sphinx-static/kernel-search.js new file +1182 -0
1,182 lines not on this page · raw message
Documentation/sphinx/templates/search.html new file +117 -0
117 lines not on this page · raw message
Documentation/sphinx/templates/searchbox.html new file +30 -0
@@ -0,0 +1,30 @@ +{# SPDX-License-Identifier: GPL-2.0 #} + +{# Sphinx sidebar template: quick search box plus advanced search link. #} +{%- if pagename != "search" and builder != "singlehtml" %} +<search id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">{{ _('Quick search') }}</h3> + <div class="searchformwrapper"> + <form class="search" action="{{ pathto('search') }}" method="get"> + <input + type="text" + name="q" + aria-labelledby="searchlabel" + autocomplete="off" + autocorrect="off" + autocapitalize="off" + spellcheck="false" + /> + <input type="submit" value="{{ _('Go') }}" /> + </form> + </div> + <p class="search-advanced-link"> + {# + Keep this entrypoint using ?advanced=1 so the full search page + opens with advanced filters enabled. + #} + <a href="{{ pathto('search') }}?advanced=1">{{ _('Advanced search') }}</a> + </p> +</search> +<script>document.getElementById('searchbox').style.display = "block"</script> +{%- endif %}
MAINTAINERS +10 -0
@@ -7652,6 +7652,16 @@ X: Documentation/power/ X: Documentation/spi/ X: Documentation/userspace-api/media/ +DOCUMENTATION ADVANCED SEARCH +R: Rito <[email protected]> +L: [email protected] +S: Maintained +F: Documentation/sphinx-static/kernel-search.js +F: Documentation/sphinx-static/custom.css +F: Documentation/sphinx/templates/search.html +F: Documentation/sphinx/templates/searchbox.html +F: tools/docs/test_advanced_search.py + DOCUMENTATION PROCESS M: Jonathan Corbet <[email protected]> R: Shuah Khan <[email protected]>
tools/docs/test_advanced_search.py new file +312 -0
312 lines not on this page · raw message
Signature · 1 line
2.51.0
PATCH v3 2/2 docs: add advanced search benchmark harness and instrumentation
In reply to Rito RhymesAdd lightweight app-side timing instrumentation to kernel-search.js that records per-phase search timings and search-index readiness markers in a window.__kernelSearchPerf global. The instrumentation is passive and does not alter search behavior.
Add a standalone Playwright benchmark harness for measuring advanced search behavior against one or more built documentation trees. The harness does not vendor or install Playwright in-tree; it points at an existing local Playwright install and runs as an external developer tool.
The harness captures request counts, transferred bytes, startup/index timings, result-kind composition, and Pages summary-loading behavior across baseline, poor-network, failure-injection, and fresh-navigation recovery scenarios. It exercises the current advanced-search Pages tab, supports both limited and unbounded Pages summary modes, and can also collect coarse CDP page metrics and the app-side phase timings exposed by the instrumentation above. Result-kind metadata is recorded so compatibility runs stay self-describing across supported Sphinx versions.
---
The harness was used for comparative local runs against stock Quick Search and to validate the current runtime behavior of advanced search across narrow, medium, and broad queries.
In those runs, the default advanced view stayed flat across the tested queries and avoided page-summary fetching entirely, while stock scaled summary-loading work with query breadth. In limited Pages mode, the advanced view loaded 10 summaries for landlock, 23 for futex, and 50 for kernel.
Playwright is a good fit for this harness because the feature is fundamentally a browser-side interface and needs end-to-end exercise at that level. The harness is kept external because Playwright is not used elsewhere in the kernel tree and is not intended to become a documentation build dependency.
The tool is optional developer-side validation infrastructure. It is useful for comparative benchmarking now, and it also provides a concrete way to measure regressions or behavior changes if the search UI is tuned or extended later.
Documentation/doc-guide/sphinx.rst | 29 + Documentation/sphinx-static/kernel-search.js | 96 +- MAINTAINERS | 1 + tools/docs/bench_search_playwright.mjs | 1278 ++++++++++++++++++ 4 files changed, 1397 insertions(+), 7 deletions(-) create mode 100755 tools/docs/bench_search_playwright.mjs
Documentation/doc-guide/sphinx.rst +29 -0
@@ -255,6 +255,35 @@ To verify full-site support for a change, also run at least one full ``make htmldocs`` build and manually exercise the generated ``search.html`` page. +Benchmark Harness +~~~~~~~~~~~~~~~~~ + +For larger behavior or performance changes, the Playwright benchmark +harness can compare stock and advanced search against already-built +documentation trees. + +The harness lives at ``tools/docs/bench_search_playwright.mjs``. It does +not install Playwright itself; point it at an existing Playwright module +with the ``PLAYWRIGHT_MODULE`` environment variable or the +``--playwright-module`` command-line option. + +A typical workflow is: + +1. Build each documentation tree you want to compare. +2. Serve each ``Documentation/output`` directory locally, for example with + ``python3 -m http.server``. +3. Run ``node tools/docs/bench_search_playwright.mjs`` with a variant + label, a local URL, a query, and an output path or output directory. + +For comparative runs, build and serve one documentation tree per target +you want to benchmark. + +For the full option set, including scenario selection, failure +injection, network throttling, startup timing collection, and optional +app timings, run:: + + node tools/docs/bench_search_playwright.mjs --help + To disable the feature and return to the theme's default Quick Search setup, remove the two template overrides:
Documentation/sphinx-static/kernel-search.js +89 -7
141 lines not on this page · raw message
MAINTAINERS +1 -0
@@ -7661,6 +7661,7 @@ F: Documentation/sphinx-static/custom.css F: Documentation/sphinx/templates/search.html F: Documentation/sphinx/templates/searchbox.html F: tools/docs/test_advanced_search.py +F: tools/docs/bench_search_playwright.mjs DOCUMENTATION PROCESS M: Jonathan Corbet <[email protected]>
tools/docs/bench_search_playwright.mjs new file +1278 -0
1,278 lines not on this page · raw message
Signature · 1 line
2.51.0
kernel test robot
build botRe: [PATCH v3 2/2] docs: add advanced search benchmark harness and instrumentation
kernel test robot noticed the following build warnings:
Hi Rito,
kernel test robot noticed the following build warnings:
[auto build test WARNING on lwn/docs-next]
[also build test WARNING on linus/master v7.0-rc6 next-20260403] [If your patch is applied to the wrong git tree, kindly drop us a note. And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Rito-Rhymes/docs-add-advanced-search-for-kernel-documentation/20260405-132032 base: git://git.lwn.net/linux.git docs-next patch link: https://lore.kernel.org/r/20260404073413.32309-3-rito%40ritovision.com patch subject: [PATCH v3 2/2] docs: add advanced search benchmark harness and instrumentation compiler: clang version 20.1.8 (https://github.com/llvm/llvm-project 87f0227cb60147a26a1eeb4fb06e3b505e9c7261) docutils: docutils (Docutils 0.21.2, Python 3.13.5, on linux) reproduce: (https://download.01.org/0day-ci/archive/20260405/[email protected]/reproduce)
If you fix the issue in a separate patch/commit (i.e. not just a new version of the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <[email protected]>
| Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/
All warnings (new ones prefixed by >>):
Warning: Documentation/devicetree/bindings/mfd/motorola-cpcap.txt references a file that doesn't exist: Documentation/devicetree/bindings/rtc/cpcap-rtc.txt
Warning: Documentation/devicetree/bindings/regulator/siliconmitus,sm5703-regulator.yaml references a file that doesn't exist: Documentation/devicetree/bindings/mfd/siliconmitus,sm5703.yaml
Warning: Documentation/devicetree/bindings/rtc/motorola,cpcap-rtc.yaml references a file that doesn't exist: Documentation/devicetree/bindings/mfd/motorola,cpcap.yaml
Warning: Documentation/doc-guide/parse-headers.rst references a file that doesn't exist: Documentation/userspace-api/media/Makefile
Warning: Documentation/leds/leds-lp5812.rst references a file that doesn't exist: Documentation/ABI/testing/sysfs-class-led-multicolor.rst
>> Warning: Documentation/sphinx-static/kernel-search.js references a file that doesn't exist: Documentation/search.html
Warning: Documentation/translations/it_IT/doc-guide/parse-headers.rst references a file that doesn't exist: Documentation/userspace-api/media/Makefile
Warning: Documentation/translations/ja_JP/SubmittingPatches references a file that doesn't exist: linux-2.6.12-vanilla/Documentation/dontdiff
Warning: Documentation/translations/ja_JP/process/submit-checklist.rst references a file that doesn't exist: Documentation/translations/ja_JP/SubmitChecklist
Warning: Documentation/translations/zh_CN/doc-guide/parse-headers.rst references a file that doesn't exist: Documentation/userspace-api/media/Makefile
Warning: Documentation/translations/zh_CN/filesystems/gfs2-glocks.rst references a file that doesn't exist: Documentation/filesystems/gfs2-glocks.rst
Signature · 2 lines
0-DAY CI Kernel Test Service https://github.com/intel/lkp-tests/wiki
Re: [PATCH v3 0/2] docs: advanced search with benchmark harness
In reply to Rito RhymesRandy, I meant to include you on the v3 reroll; this new version is intended to address the compatibility issue you hit earlier in our initial test and debugging (among other improvements).
I believe the problem came from version-dependent differences in the generated Sphinx search data, so this reroll hardens the compatibility handling around those differences and the search logic that consumes the data.
If you have time to try it again with the setup that exposed the problem before, I would appreciate confirmation that the updated version behaves correctly there.
I would also appreciate your broader assessment of the feature:
whether it seems genuinely useful in practice, how large the benefit is relative to the current Quick Search interface, how many other users you think would benefit from it, and whether you see any remaining issues or obvious room for improvement.
Rito
Randy Dunlap
reviewerRe: [PATCH v3 0/2] docs: advanced search with benchmark harness
Hi,
Quoted 13 lines · Rito Rhymes
Randy, I meant to include you on the v3 reroll; this new version is intended to address the compatibility issue you hit earlier in our initial test and debugging (among other improvements).
I believe the problem came from version-dependent differences in the generated Sphinx search data, so this reroll hardens the compatibility handling around those differences and the search logic that consumes the data.
If you have time to try it again with the setup that exposed the problem before, I would appreciate confirmation that the updated version behaves correctly there.
Quoted 5 lines
I would also appreciate your broader assessment of the feature:
whether it seems genuinely useful in practice, how large the benefit is relative to the current Quick Search interface, how many other users you think would benefit from it, and whether you see any remaining issues or obvious room for improvement.
I like it. I think it's useful -- the old search could give a bit too much output. The search result tabs (groups) are helpful.
But it will be up to Jon whether its usefulness exceeds its complications.
Also, I'm not sure that Linux developer mailing lists will reach the right audience for feedback about this change.
I mostly use 'grep' for searching Documentation/ and I expect lots of other developers also do that (if they bother to look). So I don't know who will be the largest user(s) of this feature. I.e., I don't know who uses docs.kernel.org.
I do notice under the Pages tab that all of the pages listed say "Summary unavailable." I don't know what should be there instead of that message.
Signature · 1 line
~Randy
Re: [PATCH v3 0/2] docs: advanced search with benchmark harness
Quoted 2 lines
I like it. I think it's useful -- the old search could give a bit too much output. The search result tabs (groups) are helpful.
Thanks for taking the time to test it out again and give feedback. I'm glad you see potential utility for it.
Quoted 2 lines
I mostly use 'grep' for searching
Documentation/and I expect lots of other developers also do that (if they bother to look).
That's definitely what I expect kernel hackers to default to.
I'd like to get a clearer sense of your perspective, it may represent others too, and I can weigh it against my own assumptions here.
So my question framed for you is:
You know a particular concept you want to look up, but you do not know the exact file, and related words repeat a lot across the source.
Could you imagine yourself going through grep results, not quickly finding what you need, burning mental bandwidth and then deciding:
"let me just go on docs.kernel.org real quick, hit the advanced search, and see what I find"?
Is that something you could actually see ever happening?
Maybe even, in that type of situation, eventually defaulting to that mode first to avoid spending time scanning through noisy grep results.
Or is grep and staying in the terminal a comfortable enough place to remain even when the results are not very fruitful and the time spent there is not especially efficient?
Or does that situation just not come up often enough to justify a separate mental workflow for it outside the grep norm?
Quoted 3 lines
I do notice under the Pages tab that all of the pages listed say "Summary unavailable." I don't know what should be there instead of that message.
It's supposed to be populated with an excerpt from the page related to the search criterion; 2-3 lines of text or so.
I encountered that same issue after an incremental rebuild, doing a full rebuild fixed it.
Could you please confirm if it works after a full rebuild?
Rito
Randy Dunlap
reviewerRe: [PATCH v3 0/2] docs: advanced search with benchmark harness
Quoted 19 lines · Rito Rhymes
Quoted 2 lines
I like it. I think it's useful -- the old search could give a bit too much output. The search result tabs (groups) are helpful.
Thanks for taking the time to test it out again and give feedback. I'm glad you see potential utility for it.
Quoted 2 lines
I mostly use 'grep' for searching
Documentation/and I expect lots of other developers also do that (if they bother to look).That's definitely what I expect kernel hackers to default to.
I'd like to get a clearer sense of your perspective, it may represent others too, and I can weigh it against my own assumptions here.
So my question framed for you is:
You know a particular concept you want to look up, but you do not know the exact file, and related words repeat a lot across the source.
Quoted 6 lines
Could you imagine yourself going through grep results, not quickly finding what you need, burning mental bandwidth and then deciding:
"let me just go on docs.kernel.org real quick, hit the advanced search, and see what I find"?Is that something you could actually see ever happening?
It would take a while for me to give up on grep, but eventually I could see using Advanced Search - but not quickly.
Quoted 2 lines
Maybe even, in that type of situation, eventually defaulting to that mode first to avoid spending time scanning through noisy grep results.
That would only come after several cases where Adv. Search proved to be more useful than grep.
Quoted 3 lines
Or is grep and staying in the terminal a comfortable enough place to remain even when the results are not very fruitful and the time spent there is not especially efficient?
Nice characterization :)
But yes, grep + terminal will remain the default for now.
Quoted 2 lines
Or does that situation just not come up often enough to justify a separate mental workflow for it outside the grep norm?
For me it probably does not.
Quoted 11 lines
Quoted 3 lines
I do notice under the Pages tab that all of the pages listed say "Summary unavailable." I don't know what should be there instead of that message.
It's supposed to be populated with an excerpt from the page related to the search criterion; 2-3 lines of text or so.
I encountered that same issue after an incremental rebuild, doing a full rebuild fixed it.
Could you please confirm if it works after a full rebuild?
Same result for me - Summary unavailable.
Signature · 1 line
~Randy