Revert "feat: allow configuring custom_autocompletions list" (#2014)

elixir-lang · Jan 9, 2025 · 97edc48 · 97edc48
1 parent 383d53a
commit 97edc48
Show file tree

Hide file tree

Showing 6 changed files with 14 additions and 115 deletions.
diff --git a/assets/js/autocomplete/suggestions.js b/assets/js/autocomplete/suggestions.js
@@ -18,8 +18,7 @@ const SUGGESTION_CATEGORY = {
   moduleChild: 'module-child',
   mixTask: 'mix-task',
   extra: 'extra',
-  section: 'section',
-  custom: 'custom'
+  section: 'section'
 }
 
 /**
@@ -43,8 +42,7 @@ 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'),
-    ...findSuggestionsInCustomSidebarNodes(nodes.custom || [], query, SUGGESTION_CATEGORY.custom, 'custom')
+    ...findSuggestionsInSectionsOfNodes(nodes.extras, query, SUGGESTION_CATEGORY.section, 'page')
   ].filter(suggestion => suggestion !== null)
 
   return sort(suggestions).slice(0, limit)
@@ -57,13 +55,6 @@ 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.
  */
@@ -113,25 +104,7 @@ function nodeSuggestion (node, query, category, label) {
     description: null,
     matchQuality: matchQuality(node.title, query),
     deprecated: node.deprecated,
-    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],
+    labels: [label],
     category
   }
 }
@@ -238,8 +211,7 @@ function categoryPriority (category) {
     case SUGGESTION_CATEGORY.module: return 1
     case SUGGESTION_CATEGORY.moduleChild: return 2
     case SUGGESTION_CATEGORY.mixTask: return 3
-    case SUGGESTION_CATEGORY.custom: return 4
-    default: return 5
+    default: return 4
   }
 }
 

diff --git a/lib/ex_doc/config.ex b/lib/ex_doc/config.ex
@@ -12,13 +12,6 @@ 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: [],
@@ -39,7 +32,6 @@ defmodule ExDoc.Config do
             groups_for_extras: [],
             groups_for_docs: [],
             groups_for_modules: [],
-            custom_autocompletions: [],
             homepage_url: nil,
             language: "en",
             logo: nil,
@@ -71,7 +63,6 @@ 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),
@@ -123,7 +114,6 @@ 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(
@@ -141,7 +131,6 @@ 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),
@@ -166,12 +155,6 @@ 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 --git a/lib/ex_doc/formatter/html.ex b/lib/ex_doc/formatter/html.ex
@@ -183,9 +183,7 @@ defmodule ExDoc.Formatter.HTML do
   end
 
   defp generate_sidebar_items(nodes_map, extras, config) do
-    content =
-      Templates.create_sidebar_items(nodes_map, extras, config.custom_autocompletions || [])
-
+    content = Templates.create_sidebar_items(nodes_map, extras)
     path = "dist/sidebar_items-#{digest(content)}.js"
     File.write!(Path.join(config.output, path), content)
     [path]

diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex
@@ -70,13 +70,12 @@ 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, custom_autocompletions \\ []) do
+  def create_sidebar_items(nodes_map, extras) 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 --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex
@@ -102,9 +102,6 @@ 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/"]`
@@ -156,8 +153,7 @@ 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"}`.
-       See the "Changing documentation over time" section below for more.
+       value is the path to redirect to. The extension is omitted in both cases, i.e `%{"old-readme" => "readme"}`
 
     * `: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
@@ -343,12 +339,14 @@ defmodule Mix.Tasks.Docs do
 
   ## 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:
+  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.
+    * 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.
@@ -363,29 +361,6 @@ defmodule Mix.Tasks.Docs do
         "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 --git a/test/ex_doc/formatter/html_test.exs b/test/ex_doc/formatter/html_test.exs
@@ -592,34 +592,6 @@ 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(