feat: support Ask AI (#115)

Support Ask AI with this extension.

Author: kai687

docs/conf.py

@@ -23,6 +23,11 @@
 docsearch_app_id = os.getenv("DOCSEARCH_APP_ID")
 docsearch_api_key = os.getenv("DOCSEARCH_API_KEY")
 docsearch_index_name = os.getenv("DOCSEARCH_INDEX_NAME")
+# DocSearch/Ask AI config
+# docsearch_askai = {
+#   "assistantId": "...",
+#   "indexName": "...",
+# }
 
 # Support building the docs with different themes
 # Add `-t alabaster` or `-t rtd` to the build arguments

docs/configuration.md

@@ -13,14 +13,22 @@ You can find it in the [Algolia dashboard](https://dashboard.algolia.com/account
 **`docsearch_api_key`**
 : Your Search API key.
 You can find it in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).
-
-:::{warning}
-Don't use your Write API key, which is used for crawling your content.
-:::
+  :::{warning}
+  Don't use your Write API key, which is used for crawling your content.
+  :::
 
 **`docsearch_index_name`**
 : The Algolia index name for your documentation.
 
+## Ask AI
+
+:::{versionadded} 0.2
+To get started, see [Ask AI (DocSearch)](https://docsearch.algolia.com/docs/v4/askai).
+:::
+
+`docsearch_askai`
+: A string or dictionary with [Ask AI settings](https://docsearch.algolia.com/docs/api#askai).
+
 ## Optional configuration
 
 The Sphinx extension lets you configure these aspects of the DocSearch UI.
@@ -40,15 +48,15 @@ You can change this setting if you're using a different theme.
 : Any Algolia search parameter you want to add.
 For example, to increase the maximum number of results shown, you can increase the `hitsPerPage` parameter:
 
-```python
-docsearch_search_parameters: {"hitsPerPage": 30}  # default is 20
-```
+  ```python
+  docsearch_search_parameters: {"hitsPerPage": 30}  # default is 20
+  ```
 
-:::{warning}
-This extension does not validate the search parameters.
-Check that you're providing valid parameters.
-For more information, see [Search API parameter](https://www.algolia.com/doc/api-reference/search-api-parameters/).
-:::
+  :::{warning}
+  Search parameters are passed to DocSearch without validation.
+  Check that you're providing valid parameters.
+  For more information, see [Search API parameter](https://www.algolia.com/doc/api-reference/search-api-parameters/).
+  :::
 
 **`docsearch_max_results_per_group`** (default: 5)
 : The number of results shown in each group.
@@ -61,6 +69,6 @@ for users to report issues with missing search results.
 You can include the current search query as parameter `${query}`.
 For example, create a new GitHub issue for the missing search result:
 
-```python
-docsearch_missing_results_url = "https://github.com/example/docs/issues/new?title=${query}"
-```
+  ```python
+  docsearch_missing_results_url = "https://github.com/example/docs/issues/new?title=${query}"
+  ```

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-docsearch"
-version = "0.2.0b3"
+version = "0.2.0"
 description = "A Sphinx extension for replacing the built-in search with Algolia DocSearch"
 readme = "README.md"
 authors = [

src/sphinx_docsearch/__init__.py

@@ -51,6 +51,10 @@ def check_config(app: Sphinx, config: Config) -> None:
         logger.warning(
             __("You must provide your Algolia index name for DocSearch to work.")
         )
+    if isinstance(config.docsearch_askai, dict) and "assistantId" not in config.docsearch_askai:
+        logger.warning(
+            msg=__("The docsearch_askai config value must have an assistant_id key.")
+        )
 
 
 @progress_message("DocSearch: set up")
@@ -86,6 +90,7 @@ def add_docsearch_assets(app: Sphinx, config: Config) -> None:
             "docsearch_app_id": config.docsearch_app_id,
             "docsearch_api_key": app.config.docsearch_api_key,
             "docsearch_index_name": app.config.docsearch_index_name,
+            "docsearch_askai": app.config.docsearch_askai,
             "docsearch_container": app.config.docsearch_container,
             "docsearch_initial_query": app.config.docsearch_initial_query,
             "docsearch_placeholder": app.config.docsearch_placeholder,
@@ -103,6 +108,9 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value(
         "docsearch_index_name", default="", rebuild="html", types=[str]
     )
+    app.add_config_value(
+        "docsearch_askai", default="", rebuild="html", types=[dict,str]
+    )
     app.add_config_value(
         "docsearch_container", default="#docsearch", rebuild="html", types=[str]
     )

src/sphinx_docsearch/static/docsearch.css

@@ -3,6 +3,9 @@ docsearch({
   appId: "{{ docsearch_app_id }}",
   apiKey: "{{ docsearch_api_key }}",
   indexName: "{{ docsearch_index_name }}",
+  {%- if docsearch_askai %}
+  askAi: {{ docsearch_askai|tojson }}
+  {%- endif %}
   {%- if docsearch_initial_query %}
   initialQuery: "{{ docsearch_initial_query }}",
   {%- endif %}

src/sphinx_docsearch/static/docsearch.js

@@ -12,7 +12,7 @@
 
 def test_returns_version() -> None:
     """It returns the correct version."""
-    assert sphinx_docsearch.__version__ == "0.2.0b3"
+    assert sphinx_docsearch.__version__ == "0.2.0"
 
 
 @pytest.mark.sphinx("html", confoverrides={"extensions": ["sphinx_docsearch"]})
@@ -24,6 +24,7 @@ def test_docsearch_config(app: Sphinx) -> None:
     assert not app.config.docsearch_app_id
     assert not app.config.docsearch_api_key
     assert not app.config.docsearch_index_name
+    assert not app.config.docsearch_askai
     assert app.config.docsearch_container == "#docsearch"
     assert not app.config.docsearch_initial_query
     assert not app.config.docsearch_placeholder
@@ -59,6 +60,7 @@ def test_raises_warnings(app: Sphinx, warning: StringIO) -> None:
         "docsearch_app_id": "test_app_id",
         "docsearch_api_key": "test_api_key",
         "docsearch_index_name": "test_docsearch_index_name",
+        "docsearch_askai": "test_docsearch_askai",
         "docsearch_container": "test_docsearch_container",
         "docsearch_placeholder": "test_docsearch_placeholder",
         "docsearch_initial_query": "test_docsearch_initial_query",
@@ -75,9 +77,40 @@ def test_add_docsearch_config(app: Sphinx, warning: StringIO) -> None:
     assert app.config.docsearch_app_id == "test_app_id"
     assert app.config.docsearch_api_key == "test_api_key"
     assert app.config.docsearch_index_name == "test_docsearch_index_name"
+    assert app.config.docsearch_askai == "test_docsearch_askai"
     assert app.config.docsearch_container == "test_docsearch_container"
     assert app.config.docsearch_placeholder == "test_docsearch_placeholder"
     assert app.config.docsearch_initial_query == "test_docsearch_initial_query"
     assert app.config.docsearch_search_parameters == {"hitsPerPage": 5}
     assert app.config.docsearch_max_results_per_group == 10
     assert app.config.docsearch_missing_results_url == "test_docsearch_url"
+
+
+@pytest.mark.sphinx(
+    "html",
+    confoverrides={
+        "extensions": ["sphinx_docsearch"],
+        "docsearch_askai": {"assistant_id": "wrongly_spelled_key_name"},
+    },
+)
+def test_wrong_assistant_id_key(app: Sphinx, warning: StringIO) -> None:
+    """It returns a warning for the Ask AI option."""
+    app.build()
+    warnings = warning.getvalue()
+    assert "The docsearch_askai config value must have an assistant_id key." in warnings
+    assert app.config.docsearch_askai == {"assistant_id": "wrongly_spelled_key_name"}
+
+
+@pytest.mark.sphinx(
+    "html",
+    confoverrides={
+        "extensions": ["sphinx_docsearch"],
+        "docsearch_askai": {"assistantId": "test_docsearch_assistant_id"},
+    },
+)
+def test_correct_assistant_id_key(app: Sphinx, warning: StringIO) -> None:
+    """It parses the Ask AI configuration options."""
+    app.build()
+    warnings = warning.getvalue()
+    assert "The docsearch_askai config value must have an assistant_id key." not in warnings
+    assert app.config.docsearch_askai == {"assistantId": "test_docsearch_assistant_id"}

src/sphinx_docsearch/static/docsearch_config.js_t

@@ -13,10 +13,11 @@ def test_global_context(app: Sphinx) -> None:
 
     pattern = re.compile(r"^docsearch_")
     docsearch_config = filter(pattern.search, app.builder.globalcontext)
-    assert len(list(docsearch_config)) == 9
+    assert len(list(docsearch_config)) == 10
 
     assert "docsearch_app_id" in app.builder.globalcontext
     assert "docsearch_api_key" in app.builder.globalcontext
+    assert "docsearch_askai" in app.builder.globalcontext
     assert "docsearch_index_name" in app.builder.globalcontext
     assert "docsearch_initial_query" in app.builder.globalcontext
     assert "docsearch_container" in app.builder.globalcontext