Algolia docsearch

docs/_templates/algolia-searchbox.html

@@ -0,0 +1,4 @@
+<!-- Algolia overrides the PyData theme's searchbox with this template -->
+<div role="search">
+  <div id="algolia-docsearch"></div>
+</div>

docs/conf.py

@@ -62,8 +62,9 @@
     "myst_parser",
     "sphinx_inline_tabs",
     "sphinxcontrib.bibtex",
+    "sphinx_docsearch",
     "sphinx_last_updated_by_git",
-    "nbsphinx",
+    "nbsphinx",  # to be kept below JavaScript-enabled extensions, always
     "IPython.sphinxext.ipython_console_highlighting",
     "sphinx_gallery.load_style",
     "hoverxref.extension",
@@ -155,6 +156,8 @@
     "check_switcher": True,
     # for dark mode toggle, version switcher, and social media links
     "navbar_end": ["theme-switcher", "version-switcher", "navbar-icon-links"],
+    # add Algolia to the persistent navbar, this removes the default search icon
+    "navbar_persistent": "algolia-searchbox",
     "use_edit_page_button": True,
     "pygment_light_style": "xcode",
     "pygment_dark_style": "monokai",
@@ -285,6 +288,10 @@
 
 # -- nbsphinx configuration options ------------------------------------------
 
+# Important: ensure require.js is not loaded. this is needed to avoid
+# a conflict with the sphinx-docsearch extension for Algolia search
+
+nbsphinx_requirejs_path = ""
 nbsphinx_prolog = r"""
 
 {% set github_docname =
@@ -321,31 +328,6 @@
 
 """
 
-# -- Options for sphinx-hoverxref --------------------------------------------
-
-# Hoverxref settings
-
-hoverxref_default_type = "tooltip"
-hoverxref_auto_ref = True
-
-hoverxref_roles = ["class", "meth", "func", "ref", "term"]
-hoverxref_role_types = dict.fromkeys(hoverxref_roles, "tooltip")
-
-hoverxref_domains = ["py"]
-
-# Currently, only projects that are hosted on readthedocs + CPython, NumPy, and
-# SymPy are supported
-hoverxref_intersphinx = list(intersphinx_mapping.keys())
-
-# Tooltips settings
-hoverxref_tooltip_lazy = False
-hoverxref_tooltip_maxwidth = 750
-hoverxref_tooltip_animation = "fade"
-hoverxref_tooltip_animation_duration = 1
-hoverxref_tooltip_content = "Loading information..."
-hoverxref_tooltip_theme = ["tooltipster-shadow", "tooltipster-shadow-custom"]
-
-
 # -- sphinxext/inheritance_diagram.py options --------------------------------
 
 graphviz_output_format = "svg"
@@ -396,6 +378,16 @@
 hoverxref_tooltip_content = "Loading information..."
 hoverxref_tooltip_theme = ["tooltipster-shadow", "tooltipster-shadow-custom"]
 
+# -- Options for Algolia DocSearch (sphinx-docsearch) ------------------------
+
+# DocSearch settings
+docsearch_app_id = "BXYTEF2JI8"
+docsearch_api_key = "b7e7f1fc1a7c40a1587e52e8f4ff3b45"  # search API key, safe to use
+docsearch_index_name = "pybamm"
+
+# Searchbox settings
+docsearch_container = "#algolia-docsearch"
+docsearch_placeholder = "Search the PyBaMM documentation"
 
 # -- Jinja templating --------------------------------------------------------
 # Credit to: https://ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/

docs/requirements.txt

@@ -33,3 +33,4 @@ ipykernel
 ipywidgets
 sphinx-gallery
 sphinx-hoverxref
+sphinx-docsearch

docs/source/_static/pybamm.css

@@ -167,3 +167,71 @@ html[data-theme="dark"] h3 {
 .tooltipster-sidetip.tooltipster-shadow.tooltipster-left .tooltipster-arrow-border {
   border-left-color: var(--pst-color-background) !important;
 }
+
+/* Custom styles for Algolia DocSearch v3 items and modals */
+/* to make them congruous with PST on light and dark themes */
+
+.DocSearch-Modal {
+  margin: 150px auto auto;
+  background: var(--pst-color-background);
+}
+
+.DocSearch-Container {
+  z-index: 2000;
+}
+
+kbd.DocSearch-Commands-Key {
+  border: 0;
+  box-shadow: var(--docsearch-key-shadow);
+  margin: 1px 5px 1px 0px;
+  padding: inherit;
+}
+
+html[data-theme="dark"] kbd.DocSearch-Commands-Key {
+  color: var(--pst-color-border);
+}
+
+html[data-theme="dark"] .DocSearch-Commands-Key {
+  background: linear-gradient(-26.5deg,#30474f,#31355b)
+}
+
+.DocSearch-Hit-source {
+  background: var(--pst-color-background);
+}
+.DocSearch-Button {
+  border-radius: 6px;
+}
+
+.DocSearch-Footer {
+  background: var(--pst-color-background);
+}
+
+/* Should be for both light and dark */
+
+:root {
+  --docsearch-primary-color: var(--pst-color-info);
+  --docsearch-searchbox-focus-background: var(--pst-color-background);
+  --docsearch-footer-background: var(--pst-color-on-background)
+}
+
+/* Logo in dark theme */
+
+html[data-theme="dark"] .DocSearch-Logo svg path.cls-1,
+html[data-theme="dark"] .DocSearch-Logo svg path.cls-2,
+html[data-theme="dark"] .DocSearch-Logo svg rect.cls-1 {
+ fill: var(--pst-color-white);
+}
+
+/* Logo in light theme */
+
+html[data-theme="light"] .DocSearch-Logo svg path.cls-1,
+html[data-theme="light"] .DocSearch-Logo svg path.cls-2,
+html[data-theme="light"] .DocSearch-Logo svg rect.cls-1 {
+  fill: var(--pst-color-primary);
+}
+
+/* Search field dark theme corrections */
+
+html[data-theme="dark"] .DocSearch-Button {
+  background: var(--pst-color-on-surface);
+}

setup.py

@@ -226,6 +226,7 @@ def compile_KLU():
             "ipywidgets",
             "sphinx-gallery",
             "sphinx-hoverxref",
+            "sphinx-docsearch",
         ],  # For doc generation
         "examples": [
             "jupyter",  # For example notebooks