feat: add pagefind search

Instead of using sphinx's built-in search which has some challenges
in its implementation, as well as the integration with the customized
builder and theme, use a different approach.

Pagefind will generate fragments that can be loaded client-side
efficiently.

Refs: https://pagefind.app/
Refs: https://pypi.org/project/pagefind/

Signed-off-by: Mike Fiedler <miketheman@gmail.com>

Author: miketheman

Makefile

@@ -22,6 +22,7 @@ ALLSPHINXOPTS = --builder $(BUILDER) \
 .PHONY: html
 html: venv
 	$(SPHINXBUILD) $(ALLSPHINXOPTS)
+	$(VENVDIR)/bin/python3 -m pagefind --site build --verbose
 
 ## htmlview       to open the index page built by the html target in your browser
 .PHONY: htmlview

pep_sphinx_extensions/pep_processor/transforms/pep_title.py

@@ -44,7 +44,11 @@ def apply(self) -> None:
 
         # Generate the title section node and its properties
         title_nodes = _line_to_nodes(pep_title_string)
-        pep_title_node = nodes.section("", nodes.title("", "", *title_nodes, classes=["page-title"]), names=["pep-content"])
+        # TODO: Why doesn't the new attribute show up in the HTML output?
+        # This is needed to change the way the index entry titles are generated,
+        # but is currently getting ignored/removed somewhere in the stack.
+        pep_title_attributes = {"classes": ["page-title"], "data-pagefind-meta": "title"}
+        pep_title_node = nodes.section("", nodes.title("", "", *title_nodes, **pep_title_attributes), names=["pep-content"])
 
         # Insert the title node as the root element, move children down
         document_children = self.document.children

pep_sphinx_extensions/pep_theme/templates/page.html

@@ -12,6 +12,7 @@
     <link rel="stylesheet" href="{{ pathto('_static/mq.css', resource=True) }}" type="text/css">
     <link rel="stylesheet" href="{{ pathto('_static/pygments.css', resource=True) }}" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
     <link rel="stylesheet" href="{{ pathto('_static/pygments_dark.css', resource=True) }}" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
+    <link rel="stylesheet" href="/pagefind/pagefind-ui.css" type="text/css">
     <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
     <meta property="og:title" content='{{ title + " | peps.python.org"|safe }}'>
     <meta property="og:description" content="{{ description }}">
@@ -46,11 +47,12 @@ <h1>Python Enhancement Proposals</h1>
                 <span class="visually-hidden">Toggle light / dark / auto colour theme</span>
             </button>
         </header>
-        <article>
+        <article data-pagefind-body>
             {{ body }}
         </article>
         {%- if not pagename.startswith(("404", "numerical")) %}
         <nav id="pep-sidebar">
+            <div id="search"></div>
             <h2>Contents</h2>
             {{ toc }}
             <br>
@@ -63,5 +65,11 @@ <h2>Contents</h2>
     <script src="{{ pathto('_static/colour_scheme.js', resource=True) }}"></script>
     <script src="{{ pathto('_static/wrap_tables.js', resource=True) }}"></script>
     <script src="{{ pathto('_static/sticky_banner.js', resource=True) }}"></script>
+    <script src="/pagefind/pagefind-ui.js"></script>
+    <script>
+        window.addEventListener('DOMContentLoaded', (event) => {
+            new PagefindUI({ element: "#search", showSubResults: true });
+        });
+    </script>
 </body>
 </html>

requirements.txt

@@ -5,6 +5,8 @@ Pygments >= 2.9.0
 Sphinx >= 5.1.1, != 6.1.0, != 6.1.1, < 8.1.0
 docutils >= 0.19.0
 sphinx-notfound-page >= 1.0.2
+# For search
+pagefind[bin] >= 1.3.0
 
 # For tests
 pytest