activate sphinx search (#121)

Author: flying-sheep

.prettierrc.cjs

@@ -4,6 +4,7 @@
 /** @type {import("prettier").Config} */
 module.exports = {
     plugins: [require.resolve("prettier-plugin-jinja-template")],
+    semi: false,
     overrides: [
         {
             files: [".vscode/*.json"],
@@ -21,4 +22,4 @@ module.exports = {
             },
         },
     ],
-};
+}

.vscode/settings.json

@@ -1,4 +1,5 @@
 {
+    "python.analysis.typeCheckingMode": "strict",
     "python.testing.pytestArgs": ["-vv", "--color=yes"],
     "python.testing.unittestEnabled": false,
     "python.testing.pytestEnabled": true,

docs/conf.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import os
+import re
 from typing import TYPE_CHECKING
 from pathlib import PurePosixPath
 from datetime import datetime
@@ -23,6 +25,7 @@
     "sphinx.ext.autosummary",
     "scanpydoc",
     "sphinx.ext.linkcode",  # needs to be after scanpydoc
+    "sphinx_search.extension",
 ]
 
 intersphinx_mapping = dict(
@@ -59,8 +62,6 @@
 
 def test_search(value: str, pattern: str) -> bool:
     """Tests if `pattern` can be found in `value`."""
-    import re
-
     return bool(re.search(pattern, value))
 
 
@@ -76,9 +77,17 @@ def test_search(value: str, pattern: str) -> bool:
 
 rtd_links_prefix = PurePosixPath("src")
 
+rtd_ver = os.environ.get("READTHEDOCS_VERSION", "")
+if re.fullmatch(r"\d+", rtd_ver):  # PR versions don’t have a own search index
+    rtd_sphinx_search_default_filter = (
+        f"subprojects:{os.getenv('READTHEDOCS_PROJECT')}/latest"
+    )
+
 
 def setup(app: Sphinx) -> None:
     """Set up custom Sphinx extension."""
+    if rtd_ver:  # if we’re on ReadTheDocs, hide the pydata-sphinx-theme search popup
+        app.add_js_file("scripts/rtd-sphinx-search.js", loading_method="defer")
     app.add_object_type(
         "confval",
         "confval",

pyproject.toml

@@ -24,9 +24,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = [
-    'pre-commit',
-]
+dev = ['pre-commit']
 test = [
     'pytest',
     'coverage',
@@ -37,11 +35,10 @@ test = [
 doc = [
     'scanpydoc[typehints,theme]',
     'sphinx',
+    'readthedocs-sphinx-search',
 ]
 typehints = ['sphinx-autodoc-typehints>=1.15.2']
-theme = [
-    'sphinx-book-theme>=1.1.0rc1',
-]
+theme = ['sphinx-book-theme>=1.1.0']
 
 [project.entry-points.'sphinx.html_themes']
 scanpydoc = 'scanpydoc.theme'

src/scanpydoc/theme/static/scripts/rtd-sphinx-search.js

@@ -0,0 +1,26 @@
+/**
+ * This JS is only included when the RTD Sphinx search is active.
+ */
+
+setTimeout(overrideSearchButton, 0)
+
+function overrideSearchButton() {
+    /** @type {HTMLDivElement} */
+    const search_backdrop = document.querySelector(".search__backdrop")
+    if (!search_backdrop) {
+        setTimeout(overrideSearchButton, 500)
+        return
+    }
+    search_backdrop.style.zIndex = "1020"
+
+    /** @type {HTMLButtonElement} */
+    const search_button = document.querySelector("button[aria-label='Search']")
+    search_button.addEventListener("click", () => {
+        showSearchModal()
+
+        // hide the theme’s search popup
+        /** @type {HTMLDivElement} */
+        const theme_popup = document.querySelector(".search-button__wrapper")
+        theme_popup.style.display = "none"
+    })
+}

src/scanpydoc/theme/theme.conf

@@ -1,7 +1,7 @@
 [theme]
 inherit = sphinx_book_theme
 pygments_style = tango
-sidebars = navbar-logo.html, icon-links.html, sbt-sidebar-nav.html
+sidebars = navbar-logo.html, icon-links.html, search-button-field.html, sbt-sidebar-nav.html
 stylesheet = styles/scanpy.css
 
 [options]