feat: docsearch improvements

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 4.1.0
+
+- More DocSearch configuration options
+
 ## 4.0.3
 
 - Fix canonical links

docs/conf.py

@@ -98,14 +98,11 @@
 html_collapsible_definitions = True
 html_awesome_docsearch = True
 
-# DocSearch is configured via an `.env` key here.
-# You can also use the following dictionary
-#
-# docsearch_config = {
-# "api_key": "",
-# "container": "",
-# "index_name": "",
-# }
+# The Algolia credentials are added from an `.env` file
+docsearch_config = {
+    "placeholder": "Search these docs",
+    "missing_results_url": "https://github.com/kai687/sphinxawesome-theme/issues/new?title=${query}",
+}
 
 html_theme_options = {
     "show_scrolltop": True,

docs/how-to/options.rst

@@ -36,7 +36,7 @@ To configure the theme, modify the ``html_theme_options`` dictionary in your Sph
    set ``nav_include_hidden`` to ``False``.
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
 
       # This option is `True` by default
       html_theme_options = {"nav_include_hidden": False}
@@ -52,7 +52,7 @@ To configure the theme, modify the ``html_theme_options`` dictionary in your Sph
    To hide the sidebar on all pages, set this option to `False`:
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
 
       # This option is `True` by default
       html_theme_options = {"show_nav": False}
@@ -64,7 +64,7 @@ To configure the theme, modify the ``html_theme_options`` dictionary in your Sph
    To hide the breadcrumbs, set this option to ``False``:
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
 
       # This option is `True` by default
       html_theme_options = {"show_breadcrumbs": False}
@@ -74,7 +74,7 @@ To configure the theme, modify the ``html_theme_options`` dictionary in your Sph
    To select a different separator for the breadcrumbs links, set:
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
       :emphasize-text: CHAR
 
       # The default separator is `/`
@@ -87,7 +87,7 @@ To configure the theme, modify the ``html_theme_options`` dictionary in your Sph
    To show links to the previous and next pages, set this option to ``True``:
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
 
       # This option is `False` by default
       html_theme_options = {"show_prev_next": True}
@@ -98,7 +98,7 @@ To configure the theme, modify the ``html_theme_options`` dictionary in your Sph
    set this option to ``True``:
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
 
       # This option is `False` by default
       html_theme_options = {"show_scrolltop": True}
@@ -108,7 +108,7 @@ To configure the theme, modify the ``html_theme_options`` dictionary in your Sph
    To add extra links to the header of your documentation, set the following option:
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
 
       # This option is `False` by default
       html_theme_options = {
@@ -143,7 +143,7 @@ The following options are set at the top level in your Sphinx configuration:
    such as classes or methods, collapsible.
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
 
       # This option is `False` by default
       html_collapsible_definitions = True
@@ -155,7 +155,7 @@ The following options are set at the top level in your Sphinx configuration:
    To restore Sphinx's default behavior, set this option to ``False``.
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
 
       # This option is `True` by default
       html_awesome_headerlinks = False
@@ -166,7 +166,7 @@ The following options are set at the top level in your Sphinx configuration:
    To restore Sphinx's default, set this option to ``False``.
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
 
       # This option is `True` by default
       html_awesome_code_headers = False
@@ -176,38 +176,86 @@ The following options are set at the top level in your Sphinx configuration:
    Set this option to ``True`` to use `Algolia DocSearch <https://docsearch.algolia.com/>`_ instead of the built-in search.
 
    .. code-block:: python
-      :caption: "File: conf.py"
+      :caption: File: conf.py
 
       # This option is `False` by default
       html_awesome_docsearch = True
 
-   .. rubric:: Configure DocSearch via environment variables
+Configure Algolia DocSearch
+---------------------------
 
-   Add the following environment variables, either on the command line, or as a :file:`.env` file:
+Algolia DocSearch is a third-party service.
+You need to `apply <https://docsearch.algolia.com/apply/>`_ and receive your credentials before you can use it.
 
-   `DOCSEARCH_APP_ID`
-      The id of your Algolia app
+To make DocSearch work with Sphinx,
+you need to add your credentials to the Sphinx configuration,
+or via environment variables.
 
-   `DOCSEARCH_API_KEY`
-      The API key for searching your index on Algolia
+Configure DocSearch via environment variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   `DOCSEARCH_INDEX_NAME`
-      The name of your Algolia index for your documentation project.
+Add the following environment variables, either in your shell or continuous integration environment, or add them to a :file:`.env` file:
 
-   .. rubric:: Configure DocSearch in the Sphinx configuration file
+`DOCSEARCH_APP_ID`
+   The id of your Algolia DocSearch application
 
-   Add the following to the ``docsearch_config`` dictionary in your Sphinx configuration:
+`DOCSEARCH_API_KEY`
+   The API key for searching your index on Algolia
 
-   .. code-block:: python
-      :caption: "File: conf.py"
+`DOCSEARCH_INDEX_NAME`
+   The name of your Algolia index for your documentation project
 
-      docsearch_config = {
-        app_id: "",
-        api_key: "",
-        index_name: ""
-      }
+.. note::
+
+   If you don't provide the app id, API key, or index name,
+   your Sphinx project will still build.
+   The DocSearch modal won't show any results and you might see errors in your browser's console.
+
+
+You can change these **optional** settings:
+
+`DOCSEARCH_INITIAL_QUERY`
+   If you want to show initial results when the DocSearch modal opens
+
+`DOCSEARCH_PLACEHOLDER`
+   If you want to show a different placeholder (default: "Search docs")
+
+`DOCSEARCH_SEARCH_PARAMETERS`
+   If you want to add `search parameter <https://www.algolia.com/doc/api-reference/search-api-parameters/>`_
+
+`DOCSEARCH_MISSING_RESULTS_URL`
+   If you want to let users send you a message, or file a GitHub issue,
+   when they can't find what they're looking for.
+   You can use the current query in the URL. For example:
+
+   .. code-block:: sh
+
+      DOCSEARCH_MISSING_RESULTS_URL=https://github.com/example/docs/issues/new?title=${query}
 
    .. note::
 
-      Algolia DocSearch is an external service.
-      You need to apply and receive your credentials before you can use it.
+      In the |product|, you have to provide the URL as a string.
+      This deviates from the original DocSearch implementation,
+      which accepts a function.
+
+.. seealso::
+
+   `DocSearch API reference <https://docsearch.algolia.com/docs/api/>`_.
+
+Configure DocSearch in the Sphinx configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can configure DocSearch with the ``docsearch_config`` dictionary in your Sphinx configuration:
+
+.. code-block:: python
+   :caption: File: conf.py
+
+   docsearch_config = {
+       app_id: "",
+       api_key: "",
+       index_name: ""
+       initial_query: "",
+       placeholder: "",
+       search_parameters: "",
+       missing_results_url: ""
+   }

docs/index.md

@@ -57,7 +57,7 @@ In the **How-to** section, you can learn more about using and customizing the th
 ```{toctree}
 ---
 maxdepth: 1
-caption: How-To
+caption: How To
 ---
 
 how-to/install

src/sphinxawesome_theme/docsearch.py

@@ -48,6 +48,18 @@ def setup_docsearch(
             os.getenv("DOCSEARCH_INDEX_NAME")
             or app.config.docsearch_config.get("index_name")
         ),
+        "initial_query": (
+            os.getenv("DOCSEARCH_INITIAL_QUERY")
+            or app.config.docsearch_config.get("initial_query", "")
+        ),
+        "placeholder": (
+            os.getenv("DOCSEARCH_PLACEHOLDER")
+            or app.config.docsearch_config.get("placeholder", "")
+        ),
+        "missing_results_url": (
+            os.getenv("DOCSEARCH_MISSING_RESULTS_URL")
+            or app.config.docsearch_config.get("missing_results_url", "")
+        ),
     }
     # If we want to use `docsearch` we don't need any other JS file from Sphinx
     context["script_files"] = []

src/sphinxawesome_theme/static/docsearch_config.js_t

@@ -4,5 +4,19 @@ docsearch({
   appId: "{{ docsearch_config.app_id }}",
   apiKey: "{{ docsearch_config.api_key }}",
   indexName: "{{ docsearch_config.index_name }}",
+  {%- if docsearch_config.initial_query %}
+  initialQuery: "{{ docsearch_config.initial_query }}",
+  {%- endif %}
+  {%- if docsearch_config.placeholder %}
+  placeholder: "{{ docsearch_config.placeholder|default('Search docs') }}",
+  {%- endif %}
+  {%- if docsearch_config.search_parameters %}
+  searchParameters: "{{ docsearch_config.search_parameters }}",
+  {%- endif %}
+  {%- if docsearch_config.missing_results_url %}
+  getMissingResultsUrl({ query }) {
+    return `{{ docsearch_config.missing_results_url }}`
+  }
+  {%- endif %}
 });
 {%- endif %}

src/theme-src/js/docsearch_config.js_t

@@ -4,5 +4,19 @@ docsearch({
   appId: "{{ docsearch_config.app_id }}",
   apiKey: "{{ docsearch_config.api_key }}",
   indexName: "{{ docsearch_config.index_name }}",
+  {%- if docsearch_config.initial_query %}
+  initialQuery: "{{ docsearch_config.initial_query }}",
+  {%- endif %}
+  {%- if docsearch_config.placeholder %}
+  placeholder: "{{ docsearch_config.placeholder|default('Search docs') }}",
+  {%- endif %}
+  {%- if docsearch_config.search_parameters %}
+  searchParameters: "{{ docsearch_config.search_parameters }}",
+  {%- endif %}
+  {%- if docsearch_config.missing_results_url %}
+  getMissingResultsUrl({ query }) {
+    return `{{ docsearch_config.missing_results_url }}`
+  }
+  {%- endif %}
 });
 {%- endif %}

src/theme-src/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphinxawesome-theme",
-  "version": "3.3.7",
+  "version": "4.0.3",
   "scripts": {
     "build": "NODE_ENV=production webpack",
     "dev": "NODE_ENV=development webpack --watch --progress",

src/theme-src/yarn.lock

@@ -3322,7 +3322,7 @@ mz@^2.7.0:
     object-assign "^4.0.1"
     thenify-all "^1.0.0"
 
-nanoid@^3.3.4:
+nanoid@^3.3.6:
   version "3.3.6"
   resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-3.3.6.tgz#443380c856d6e9f9824267d960b4236ad583ea4c"
   integrity sha512-BGcqMMJuToF7i1rt+2PWSNVnWIkGCU78jBG3RxO/bZlnZPK2Cmi2QaffxGO/2RvWi9sL+FAiRiXMgsyxQ1DIDA==
@@ -4119,11 +4119,11 @@ postcss-zindex@^6.0.0:
   integrity sha512-lNim6f01ClwALn0J50yyoR+qOu10GXub+xucEB7+x8VwXl+iNJSj/QgXg45XpSoLsWD5HIofVrG/pPrMFcdbig==
 
 postcss@^8.0.9, postcss@^8.4.19, postcss@^8.4.21:
-  version "8.4.21"
-  resolved "https://registry.yarnpkg.com/postcss/-/postcss-8.4.21.tgz#c639b719a57efc3187b13a1d765675485f4134f4"
-  integrity sha512-tP7u/Sn/dVxK2NnruI4H9BG+x+Wxz6oeZ1cJ8P6G/PZY0IKk4k/63TDsQf2kQq3+qoJeLm2kIBUNlZe3zgb4Zg==
+  version "8.4.22"
+  resolved "https://registry.yarnpkg.com/postcss/-/postcss-8.4.22.tgz#c29e6776b60ab3af602d4b513d5bd2ff9aa85dc1"
+  integrity sha512-XseknLAfRHzVWjCEtdviapiBtfLdgyzExD50Rg2ePaucEesyh8Wv4VPdW0nbyDa1ydbrAxV19jvMT4+LFmcNUA==
   dependencies:
-    nanoid "^3.3.4"
+    nanoid "^3.3.6"
     picocolors "^1.0.0"
     source-map-js "^1.0.2"