DocSearch (#26)

Co-authored-by: Isaac Virshup <[email protected]>

Author: flying-sheep

scanpydoc/theme/__init__.py

@@ -9,7 +9,8 @@
 Theme options
 =============
 
-This theme only adds one configuration value:
+This theme adds the following configuration option,
+and the ones under `docsearch options`_:
 
 .. confval:: accent_color
 
@@ -28,6 +29,43 @@
        display_version=False,
    )
 
+Docsearch options
+-----------------
+
+These two configuration values are required to use docsearch_:
+
+.. _docsearch: https://docsearch.algolia.com/
+
+.. confval:: docsearch_key
+
+   :type: str
+
+   The API key provided by docsearch.
+
+.. confval:: docsearch_index
+
+   :type: str
+
+   The index name used by docsearch.
+
+The following configuration values are optional:
+
+.. confval:: docsearch_doc_version
+
+   :type: str
+   :default: ``'latest'`` or ``'stable'``
+
+   The documentation version searched.
+   The default is ``'stable'`` if ``READTHEDOCS_VERSION=stable`` is set,
+   and ``'latest'`` otherwise.
+
+.. confval:: docsearch_js_version
+
+   :type: str
+   :default: ``'2.6'``
+
+   The docsearch library version used.
+
 """
 
 from pathlib import Path

scanpydoc/theme/layout.html

@@ -1,4 +1,14 @@
 {% extends "sphinx_rtd_theme/layout.html" %}
+
+<!-- Have to use htmltitle to include this earlier as our style -->
+{%- block htmltitle %}
+{{ super() }}
+{% if theme_docsearch_key and theme_docsearch_index %}
+<link rel=stylesheet href="https://cdn.jsdelivr.net/npm/docsearch.js@{{ theme_docsearch_js_version }}/dist/cdn/docsearch.min.css"/>
+{% endif %}
+{%- endblock -%}
+
+<!-- Styles that come last -->
 {%- block extrahead %}
 {{ super() }}
 {% if theme_accent_color %}
@@ -7,3 +17,21 @@
 </style>
 {% endif %}
 {% endblock %}
+
+{% set safe_version = version if version in ["latest", "stable"] else "latest" %}
+
+{% block scripts %}
+{{ super() }}
+{% if theme_docsearch_key and theme_docsearch_index %}
+<script src="https://cdn.jsdelivr.net/npm/docsearch.js@{{ theme_docsearch_js_version }}/dist/cdn/docsearch.min.js"></script>
+<script>
+  document.addEventListener('DOMContentLoaded', () => docsearch({
+    apiKey: '{{ theme_docsearch_key }}',
+    indexName: '{{ theme_docsearch_index }}',
+    inputSelector: '#rtd-search-form > input[name="q"]',
+    algoliaOptions: { facetFilters: ['version:{{ theme_docsearch_doc_version or safe_version }}'] },
+    debug: false,
+  }))
+</script>
+{% endif %}
+{% endblock %}

scanpydoc/theme/static/css/scanpy.css

@@ -9,7 +9,18 @@
 .wy-side-nav-search input[type="text"] { border-width: 0 }
 .wy-side-nav-search a.icon-home { font-size: 2em; color: var(--accent-color) }
 .wy-side-nav-search a.icon-home::before { content: none }
+.wy-menu li a { overflow: hidden; text-overflow: ellipsis; }  /* display ellipsis in long items */
 
+/* DocSearch adaptations */
+
+.wy-nav-side { overflow: visible; }
+.wy-side-scroll { overflow: inherit; }
+
+/* Making it a bit wider */
+.algolia-autocomplete .ds-dropdown-menu {
+  max-width: 1000px;
+  min-width: 80vw;
+}
 
 /* Custom classes */
 

scanpydoc/theme/theme.conf

@@ -18,3 +18,7 @@ style_external_links = False
 style_nav_header_background =
 # added by scanpydoc
 accent_color =
+docsearch_key =
+docsearch_index =
+docsearch_doc_version =
+docsearch_js_version = 2.6