diff --git a/assets/js/autocomplete/suggestions.js b/assets/js/autocomplete/suggestions.js index 376c982fa..f4900f977 100644 --- 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 index fff8deace..a259edc1e 100644 --- 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 index 478dc9528..4f9d56d6c 100644 --- 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 index b9f20d625..a4ab93a9a 100644 --- 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 index 4c588e9a5..e137cb1cb 100644 --- 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 index 86c4a8e08..bc24d8bb0 100644 --- 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(