Tests

Author: josevalim

lib/ex_doc/config.ex

@@ -45,7 +45,7 @@ defmodule ExDoc.Config do
             project: nil,
             redirects: %{},
             retriever: ExDoc.Retriever,
-            search: [%{name: "Default", help: "Search in browser", url: "search.html?q="}],
+            search: [%{name: "Default", help: "In-browser search", url: "search.html?q="}],
             skip_undefined_reference_warnings_on:
               &__MODULE__.skip_undefined_reference_warnings_on/1,
             skip_code_autolink_to: &__MODULE__.skip_code_autolink_to/1,
@@ -314,7 +314,7 @@ defmodule ExDoc.Config do
   end
 
   defp normalize_search([]) do
-    [%{name: "Default", help: "Search in browser", url: "search.html?q="}]
+    [%{name: "Default", help: "In-browser search", url: "search.html?q="}]
   end
 
   defp normalize_search(search) when is_list(search) do

lib/mix/tasks/docs.ex

@@ -164,6 +164,24 @@ defmodule Mix.Tasks.Docs do
        value is the path to redirect to. The extension is omitted in both cases, i.e `%{"old-readme" => "readme"}`.
        See the "Changing documentation over time" section below for more.
 
+    * `:search` - A list of search engine configurations. Each search engine is a map with the following keys:
+
+        * `:name` - The display name of the search engine (required)
+        * `:help` - A help text describing what the search engine does (required)
+        * `:url` - The optional search URL template, usually ending with `q=`
+          The default uses ExDoc built-in Lunr's search engine
+
+      When multiple search engines are configured, a dropdown selector will appear next to the search bar
+      allowing users to choose which engine to use. For example:
+
+          search: [
+            %{name: "FooBar", help: "Search on FooBar", url: "https://example.com/?q="},
+            %{name: "Local", help: "In-browser search"}
+          ]
+
+      By default, the built-in Lunr's search engine is configured. If only one search engine
+      is configured, the dropdown selector will be hidden.
+
     * `:skip_undefined_reference_warnings_on` - ExDoc warns when it can't create a `Mod.fun/arity`
       reference in the current project docs (for example, because of a typo). This option controls when to
       skip such warnings. This option can be a list of strings that will be checked for exact matches,

test/ex_doc/config_test.exs

@@ -166,27 +166,38 @@ defmodule ExDoc.ConfigTest do
   describe "normalizes search" do
     test "defaults to local search" do
       config = build([])
-      assert config.search == [%{name: "Default", help: "Search in browser", url: "search.html?q="}]
+
+      assert config.search == [
+               %{name: "Default", help: "In-browser search", url: "search.html?q="}
+             ]
     end
 
     test "accepts list of maps with name, help, and url" do
-      config = build(search: [
-        %{name: "Google", help: "Search using Google", url: "https://google.com/?q="},
-        %{name: "Local", help: "Search locally", url: "search.html?q="}
-      ])
+      config =
+        build(
+          search: [
+            %{name: "Google", help: "Search using Google", url: "https://google.com/?q="},
+            %{name: "Local", help: "Search locally", url: "search.html?q="}
+          ]
+        )
 
       assert config.search == [
-        %{name: "Google", help: "Search using Google", url: "https://google.com/?q="},
-        %{name: "Local", help: "Search locally", url: "search.html?q="}
-      ]
+               %{name: "Google", help: "Search using Google", url: "https://google.com/?q="},
+               %{name: "Local", help: "Search locally", url: "search.html?q="}
+             ]
     end
 
     test "defaults url to search.html?q= when not provided" do
-      config = build(search: [
-        %{name: "Default", help: "Search in browser"}
-      ])
+      config =
+        build(
+          search: [
+            %{name: "Default", help: "In-browser search"}
+          ]
+        )
 
-      assert config.search == [%{name: "Default", help: "Search in browser", url: "search.html?q="}]
+      assert config.search == [
+               %{name: "Default", help: "In-browser search", url: "search.html?q="}
+             ]
     end
 
     test "raises on invalid search config" do

test/ex_doc/formatter/html/templates_test.exs

@@ -81,10 +81,13 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
 
   describe "sidebar" do
     test "renders search engines when multiple are configured", context do
-      config = doc_config(context, search: [
-        %{name: "Google", help: "Search using Google", url: "https://google.com/?q="},
-        %{name: "Local", help: "Search locally", url: "search.html?q="}
-      ])
+      config =
+        doc_config(context,
+          search: [
+            %{name: "Google", help: "Search using Google", url: "https://google.com/?q="},
+            %{name: "Local", help: "Search locally", url: "search.html?q="}
+          ]
+        )
 
       content = Templates.sidebar_template(config, :extra)
 
@@ -96,9 +99,12 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
     end
 
     test "renders search engine when only one is configured", context do
-      config = doc_config(context, search: [
-        %{name: "Default", help: "Search in browser", url: "search.html?q="}
-      ])
+      config =
+        doc_config(context,
+          search: [
+            %{name: "Default", help: "In-browser search", url: "search.html?q="}
+          ]
+        )
 
       content = Templates.sidebar_template(config, :extra)