Allow configuring custom_autocompletions list (#2011)

Author: zachdaniel

Diff for: README.md

@@ -452,49 +452,6 @@ Similarly to the example above, if your Markdown includes Mermaid graph specific
 
 For more details and configuration options, see the [Mermaid usage docs](https://mermaid-js.github.io/mermaid/#/usage).
 
-## Changing documentation over time
-
-As your project grows, your documentation may very likely change, even structurally. There are a few important things to consider in this regard:
-
-- Links to your *extras* will break if you change or move file names.
-- Links to your *modules, and mix tasks* will change if you change their name.
-- Links to *functions* are actually links to modules with anchor links. If you change the function name, the link does
-  not break but will leave users at the top of the module's documentation.
-
-Because these docs are static files, the behavior of a missing page will depend on where they are hosted.
-In particular, [hexdocs.pm](https://hexdocs.pm) will show a 404 page.
-
-You can improve the developer experience on everything but function names changing
-by using the `redirects` configuration. For example, if you changed the module `MyApp.MyModule`
-to `MyApp.My.Module` and the extra `get-started.md` to `quickstart.md`, you can
-setup the following redirects:
-
-<!-- tabs-open -->
-
-### Elixir
-
-For this example, we've changed the module `MyApp.MyModule` to `MyApp.My.Module`, and the extra `get-started.md` to `quickstart.md`
-
-```elixir
-redirects: %{
-  "MyApp.MyModule" => "MyApp.My.Module",
-  "get-started" => "quickstart"
-}
-```
-
-### Erlang
-
-For this example, we've changed the module `:my_module` to `:my_module2`, and the extra `get-started.md` to `quickstart.md`
-
-```erlang
-{redirects, [
-  {"my_module", "my_module2"},
-  {"get-started", "quickstart"}
-]}.
-```
-
-<!-- tabs-close -->
-
 ## Contributing
 
 The easiest way to test changes to ExDoc is to locally rebuild the app and its own documentation:

Diff for: assets/js/autocomplete/suggestions.js

@@ -18,7 +18,8 @@ const SUGGESTION_CATEGORY = {
   moduleChild: 'module-child',
   mixTask: 'mix-task',
   extra: 'extra',
-  section: 'section'
+  section: 'section',
+  custom: 'custom'
 }
 
 /**
@@ -42,7 +43,8 @@ export function getSuggestions (query, limit = 8) {
     ...findSuggestionsInTopLevelNodes(nodes.extras, query, SUGGESTION_CATEGORY.extra, 'page'),
     ...findSuggestionsInSectionsOfNodes(nodes.modules, query, SUGGESTION_CATEGORY.section, 'module'),
     ...findSuggestionsInSectionsOfNodes(nodes.tasks, query, SUGGESTION_CATEGORY.section, 'mix task'),
-    ...findSuggestionsInSectionsOfNodes(nodes.extras, query, SUGGESTION_CATEGORY.section, 'page')
+    ...findSuggestionsInSectionsOfNodes(nodes.extras, query, SUGGESTION_CATEGORY.section, 'page'),
+    ...findSuggestionsInCustomSidebarNodes(nodes.custom || [], query, SUGGESTION_CATEGORY.custom, 'custom')
   ].filter(suggestion => suggestion !== null)
 
   return sort(suggestions).slice(0, limit)
@@ -55,6 +57,13 @@ function findSuggestionsInTopLevelNodes (nodes, query, category, label) {
   return nodes.map(node => nodeSuggestion(node, query, category, label))
 }
 
+/**
+ * Finds suggestions in custom sidebar nodes.
+ */
+function findSuggestionsInCustomSidebarNodes (nodes, query, category, label) {
+  return nodes.map(node => customNodeSuggestion(node, query, category, label))
+}
+
 /**
  * Finds suggestions in node groups of the given parent nodes.
  */
@@ -104,7 +113,25 @@ function nodeSuggestion (node, query, category, label) {
     description: null,
     matchQuality: matchQuality(node.title, query),
     deprecated: node.deprecated,
-    labels: [label],
+    labels: node.labels || [label],
+    category
+  }
+}
+
+/**
+ * Builds a suggestion for a custom top level node.
+ * Returns null if the node doesn't match the query.
+ */
+function customNodeSuggestion (node, query, category, label) {
+  if (!matchesAll(node.title, query)) { return null }
+
+  return {
+    link: node.link,
+    title: highlightMatches(node.title, query),
+    description: node.description,
+    matchQuality: matchQuality(node.title, query),
+    deprecated: node.deprecated,
+    labels: node.labels || [label],
     category
   }
 }
@@ -211,7 +238,8 @@ function categoryPriority (category) {
     case SUGGESTION_CATEGORY.module: return 1
     case SUGGESTION_CATEGORY.moduleChild: return 2
     case SUGGESTION_CATEGORY.mixTask: return 3
-    default: return 4
+    case SUGGESTION_CATEGORY.custom: return 4
+    default: return 5
   }
 }
 

Diff for: lib/ex_doc/config.ex

@@ -12,6 +12,13 @@ defmodule ExDoc.Config do
   def skip_undefined_reference_warnings_on(_string), do: false
   def skip_code_autolink_to(_string), do: false
 
+  @type custom_autocompletion :: %{
+          required(:link) => String.t(),
+          required(:title) => String.t(),
+          required(:description) => String.t(),
+          optional(:labels) => [String.t()]
+        }
+
   defstruct annotations_for_docs: &__MODULE__.annotations_for_docs/1,
             api_reference: true,
             apps: [],
@@ -32,6 +39,7 @@ defmodule ExDoc.Config do
             groups_for_extras: [],
             groups_for_docs: [],
             groups_for_modules: [],
+            custom_autocompletions: [],
             homepage_url: nil,
             language: "en",
             logo: nil,
@@ -63,6 +71,7 @@ defmodule ExDoc.Config do
           before_closing_body_tag: (atom() -> String.t()) | mfa() | map(),
           before_closing_footer_tag: (atom() -> String.t()) | mfa() | map(),
           before_closing_head_tag: (atom() -> String.t()) | mfa() | map(),
+          custom_autocompletions: [custom_autocompletion],
           canonical: nil | String.t(),
           cover: nil | Path.t(),
           default_group_for_doc: (keyword() -> String.t() | nil),
@@ -114,6 +123,7 @@ defmodule ExDoc.Config do
     {groups_for_docs, options} = Keyword.pop(options, :groups_for_docs, [])
     {groups_for_extras, options} = Keyword.pop(options, :groups_for_extras, [])
     {groups_for_modules, options} = Keyword.pop(options, :groups_for_modules, [])
+    {custom_autocompletions, options} = Keyword.pop(options, :custom_autocompletions, [])
 
     {skip_undefined_reference_warnings_on, options} =
       Keyword.pop(
@@ -131,6 +141,7 @@ defmodule ExDoc.Config do
       end)
 
     preconfig = %__MODULE__{
+      custom_autocompletions: normalize_custom_autocompletions(custom_autocompletions),
       filter_modules: normalize_filter_modules(filter_modules),
       groups_for_docs: normalize_groups(groups_for_docs),
       groups_for_extras: normalize_groups(groups_for_extras),
@@ -155,6 +166,12 @@ defmodule ExDoc.Config do
     struct(preconfig, options)
   end
 
+  defp normalize_custom_autocompletions(custom_autocompletions) do
+    Enum.map(custom_autocompletions, fn autocompletion ->
+      Map.new(autocompletion)
+    end)
+  end
+
   defp normalize_output(output) do
     String.trim_trailing(output, "/")
   end

Diff for: lib/ex_doc/formatter/html.ex

@@ -183,7 +183,9 @@ defmodule ExDoc.Formatter.HTML do
   end
 
   defp generate_sidebar_items(nodes_map, extras, config) do
-    content = Templates.create_sidebar_items(nodes_map, extras)
+    content =
+      Templates.create_sidebar_items(nodes_map, extras, config.custom_autocompletions || [])
+
     path = "dist/sidebar_items-#{digest(content)}.js"
     File.write!(Path.join(config.output, path), content)
     [path]

Diff for: lib/ex_doc/formatter/html/templates.ex

@@ -70,12 +70,13 @@ defmodule ExDoc.Formatter.HTML.Templates do
   @doc """
   Create a JS object which holds all the items displayed in the sidebar area
   """
-  def create_sidebar_items(nodes_map, extras) do
+  def create_sidebar_items(nodes_map, extras, custom_autocompletions \\ []) do
     nodes =
       nodes_map
       |> Enum.map(&sidebar_module/1)
       |> Map.new()
       |> Map.put(:extras, sidebar_extras(extras))
+      |> Map.put(:custom, custom_autocompletions)
 
     ["sidebarNodes=" | ExDoc.Utils.to_json(nodes)]
   end

Diff for: lib/mix/tasks/docs.ex

@@ -102,6 +102,9 @@ defmodule Mix.Tasks.Docs do
       the "assets" directory in the output path under the name "cover" and the
       appropriate extension. This option has no effect when using the "html" formatter.
 
+    * `:custom_autocompletions` - A list of maps or keywords representing custom autocomplete
+      results that will appear in the search. See the "Customizing Search" section below for more.
+
     * `:deps` - A keyword list application names and their documentation URL.
       ExDoc will by default include all dependencies and assume they are hosted on
       HexDocs. This can be overridden by your own values. Example: `[plug: "https://myserver/plug/"]`
@@ -153,7 +156,8 @@ defmodule Mix.Tasks.Docs do
       May be overridden by command line argument.
 
     * `:redirects` - A map or list of tuples, where the key is the path to redirect from and the
-       value is the path to redirect to. The extension is omitted in both cases, i.e `%{"old-readme" => "readme"}`
+       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.
 
     * `:skip_undefined_reference_warnings_on` - ExDoc warns when it can't create a `Mod.fun/arity`
       reference in the current project docs e.g. because of a typo. This list controls where to
@@ -337,6 +341,51 @@ defmodule Mix.Tasks.Docs do
   attention to them in the docs, you should probably use `:groups_for_modules`
   (which can be used in conjunction with `:nest_modules_by_prefix`).
 
+  ## Changing documentation over time
+
+  As your project grows, your documentation may very likely change, even structurally. There are a few important things to consider in this regard:
+
+  - Links to your *extras* will break if you change or move file names.
+  - Links to your *modules, and mix tasks* will change if you change their name.
+  - Links to *functions* are actually links to modules with anchor links. If you change the function name, the link does
+  not break but will leave users at the top of the module's documentation.
+
+  Because these docs are static files, the behavior of a missing page will depend on where they are hosted.
+  In particular, [hexdocs.pm](https://hexdocs.pm) will show a 404 page.
+
+  You can improve the developer experience on everything but function names changing
+  by using the `redirects` configuration. For example, if you changed the module `MyApp.MyModule`
+  to `MyApp.My.Module` and the extra `get-started.md` to `quickstart.md`, you can
+  setup the following redirects:
+
+      redirects: %{
+        "MyApp.MyModule" => "MyApp.My.Module",
+        "get-started" => "quickstart"
+      }
+
+  ## Customizing Search
+
+  In ExDoc, there are two kinds of searches. There is the "autocomplete", which is what shows up when you type in the top search bar,
+  and "search" which is the separate page with results that you arrive at if you submit the search bar without selecting an autocompleted
+  item. Currently, only the autocompletions are customizable.
+
+  You can add to the available autocompletions by specifying the `custom_autocompletions` option. This must be a list of
+  maps or keyword lists with the following shape:
+
+      custom_autocompletions: [
+        %{
+          link: "a-page.html#anchor",
+          title: "custom-text",
+          description: "Some Custom Text",
+          labels: ["Text"]
+        }
+      ]
+
+  - `link` is expected to be a relative link to a page in your documentation. You may user anchor links.
+  - `title` is the term that will be searched, and what will be shown as the primary text in the search result.
+  - `description` is text that will be shown below the search result
+  - `labels` will be shown as badges next to that content.
+
   ## Umbrella project
 
   ExDoc can be used in an umbrella project and generates a single documentation

Diff for: test/ex_doc/formatter/html_test.exs

@@ -592,6 +592,34 @@ defmodule ExDoc.Formatter.HTMLTest do
              ] = Jason.decode!(content)["extras"]
     end
 
+    test "custom autocompletions can be added", %{tmp_dir: tmp_dir} = context do
+      generate_docs(
+        doc_config(context,
+          source_beam: "unknown",
+          extras: [],
+          custom_autocompletions: [
+            %{
+              link: "a-page.html#anchor",
+              title: "custom-text",
+              description: "Some Custom Text",
+              labels: ["Text"]
+            }
+          ]
+        )
+      )
+
+      "sidebarNodes=" <> content = read_wildcard!(tmp_dir <> "/html/dist/sidebar_items-*.js")
+
+      assert [
+               %{
+                 "link" => "a-page.html#anchor",
+                 "title" => "custom-text",
+                 "description" => "Some Custom Text",
+                 "labels" => ["Text"]
+               }
+             ] = Jason.decode!(content)["custom"]
+    end
+
     test "containing settext headers while discarding links on header",
          %{tmp_dir: tmp_dir} = context do
       generate_docs(