docs: add sphinx docsearch documentation

lepture · Apr 7, 2024 · f34bd8b · f34bd8b
1 parent 0e36e4c
commit f34bd8b
Show file tree

Hide file tree

Showing 11 changed files with 54 additions and 5 deletions.
diff --git a/docs/_static/screenshots/docsearch-dark.jpg b/docs/_static/screenshots/docsearch-dark.jpg
diff --git a/docs/_static/screenshots/docsearch-light.jpg b/docs/_static/screenshots/docsearch-light.jpg
diff --git a/docs/_static/screenshots/dark-homepage.jpg → docs/_static/screenshots/homepage-dark.jpg b/docs/_static/screenshots/dark-homepage.jpg → docs/_static/screenshots/homepage-dark.jpg
diff --git a/docs/_static/screenshots/light-homepage.jpg → docs/_static/screenshots/homepage-light.jpg b/docs/_static/screenshots/light-homepage.jpg → docs/_static/screenshots/homepage-light.jpg
diff --git a/.../_static/screenshots/dark-sphinx-tabs.png → .../_static/screenshots/sphinx-tabs-dark.png b/.../_static/screenshots/dark-sphinx-tabs.png → .../_static/screenshots/sphinx-tabs-dark.png
diff --git a/..._static/screenshots/light-sphinx-tabs.png → ..._static/screenshots/sphinx-tabs-light.png b/..._static/screenshots/light-sphinx-tabs.png → ..._static/screenshots/sphinx-tabs-light.png
diff --git a/docs/customisation/announcement.rst b/docs/customisation/announcement.rst
@@ -27,10 +27,10 @@ Here shows an example with ``announcement`` configuration.
 
 .. container:: image-1
 
-    .. image:: /_static/screenshots/light-homepage.jpg
+    .. image:: /_static/screenshots/homepage-light.jpg
       :class: light-only
       :align: center
 
-    .. image:: /_static/screenshots/dark-homepage.jpg
+    .. image:: /_static/screenshots/homepage-dark.jpg
       :class: dark-only
       :align: center
diff --git a/docs/extensions/docsearch.rst b/docs/extensions/docsearch.rst
@@ -0,0 +1,48 @@
+:description: Shibuya theme works well with Algolia sphinx docsearch extension.
+
+.. _docsearch:
+
+sphinx-docsearch
+================
+
+``sphinx-docsearch`` replaces Sphinx's built-in search with Algolia DocSearch.
+
+**Documentation**: https://sphinx-docsearch.readthedocs.io/
+
+Install
+-------
+
+.. code-block:: bash
+
+    pip install sphinx-docsearch
+
+Then, add the extension to your ``conf.py``:
+
+.. code-block:: python
+    :caption: conf.py
+
+    extensions = [
+        # ...
+        "sphinx_docsearch",
+    ]
+
+    docsearch_app_id = "<DOCSEARCH_APP_ID>"
+    docsearch_api_key = "<DOCSEARCH_SEARCH_API_KEY>"
+    docsearch_index_name = "<DOCSEARCH_INDEX_NAME>"
+
+Screenshots
+-----------
+
+``sphinx-docsearch`` looks great in both light and dark mode with Shibuya theme.
+
+.. figure:: /_static/screenshots/docsearch-light.jpg
+    :class: rounded
+    :align: center
+
+    DocSearch modal in **light** mode.
+
+.. figure:: /_static/screenshots/docsearch-dark.jpg
+    :class: rounded
+    :align: center
+
+    DocSearch modal in **dark** mode.
diff --git a/docs/extensions/numpydoc.rst b/docs/extensions/numpydoc.rst
@@ -3,7 +3,7 @@
 .. _numpydoc:
 
 numpydoc
-===========
+========
 
 Numpy's Sphinx extensions to power Numpy's docstring syntax.
 

diff --git a/docs/extensions/sphinx-tabs.rst b/docs/extensions/sphinx-tabs.rst
@@ -97,10 +97,10 @@ Markup syntax
 How it looks like
 -----------------
 
-.. image:: /_static/screenshots/light-sphinx-tabs.png
+.. image:: /_static/screenshots/sphinx-tabs-light.png
    :class: light-only
    :align: center
 
-.. image:: /_static/screenshots/dark-sphinx-tabs.png
+.. image:: /_static/screenshots/sphinx-tabs-dark.png
    :class: dark-only
    :align: center
diff --git a/docs/index.rst b/docs/index.rst
@@ -75,6 +75,7 @@ Shibuya
     extensions/nbsphinx
     extensions/numpydoc
     extensions/mermaid
+    extensions/docsearch
 
 .. toctree::
     :caption: Development