Reduce the places we pass markdown globally and extend Erlang coverage

Author: josevalim

lib/ex_doc.ex

@@ -523,10 +523,6 @@ defmodule ExDoc do
     retriever = Keyword.get(options, :retriever, ExDoc.Retriever)
     extras_input = Keyword.get(options, :extras, [])
 
-    if processor = options[:markdown_processor] do
-      ExDoc.Markdown.put_markdown_processor(processor)
-    end
-
     # Build configs independently (build both upfront for validation)
     retriever_config = ExDoc.Config.build(options)
     formatter_config = ExDoc.Formatter.Config.build(project, version, options)

lib/ex_doc/cli.ex

@@ -228,7 +228,7 @@ defmodule ExDoc.CLI do
     The file must either have ".exs" or ".config" extension.
 
     The file with the ".exs" extension must be an Elixir script that returns
-    a keyword list with the same options declares in `ExDoc.generate/3`.
+    a keyword list with the same options declares in `ExDoc.generate/4`.
     Here is an example:
 
         [

lib/ex_doc/config.ex

@@ -18,7 +18,8 @@ defmodule ExDoc.Config do
             groups_for_extras: [],
             source_url_pattern: &__MODULE__.source_url_pattern/2,
             nest_modules_by_prefix: [],
-            proglang: :elixir
+            proglang: :elixir,
+            markdown_processor: {ExDoc.Markdown.Earmark, []}
 
   @type t :: %__MODULE__{
           filter_modules: (module, map -> boolean),
@@ -30,7 +31,8 @@ defmodule ExDoc.Config do
           groups_for_extras: [{binary(), term()}],
           source_url_pattern: (String.t(), integer() -> String.t() | nil),
           nest_modules_by_prefix: [String.t()],
-          proglang: :elixir | :erlang
+          proglang: :elixir | :erlang,
+          markdown_processor: {module(), keyword()} | module()
         }
 
   def build(options) do
@@ -80,8 +82,9 @@ defmodule ExDoc.Config do
 
     retriever_options =
       Keyword.take(options, [
-        :source_ref,
-        :annotations_for_docs
+        :annotations_for_docs,
+        :markdown_processor,
+        :source_ref
       ])
 
     struct!(preconfig, retriever_options)

lib/ex_doc/extras.ex

@@ -54,11 +54,10 @@ defmodule ExDoc.Extras do
   """
   def build(extras_input, config) do
     groups = config.groups_for_extras
-    source_url_pattern = config.source_url_pattern
 
     extras =
       extras_input
-      |> Enum.map(&build_extra(&1, groups, source_url_pattern))
+      |> Enum.map(&build_extra(&1, groups, config))
 
     ids_count = Enum.reduce(extras, %{}, &Map.update(&2, &1.id, 1, fn c -> c + 1 end))
 
@@ -74,15 +73,15 @@ defmodule ExDoc.Extras do
     Map.put(extra, :id, "#{extra.id}-#{discriminator}")
   end
 
-  defp build_extra(input, groups, source_url_pattern) when is_binary(input) do
-    build_extra({input, %{}}, groups, source_url_pattern)
+  defp build_extra(input, groups, config) when is_binary(input) do
+    build_extra({input, %{}}, groups, config)
   end
 
-  defp build_extra({input, opts}, groups, source_url_pattern) when is_list(opts) do
-    build_extra({input, Map.new(opts)}, groups, source_url_pattern)
+  defp build_extra({input, opts}, groups, config) when is_list(opts) do
+    build_extra({input, Map.new(opts)}, groups, config)
   end
 
-  defp build_extra({input, %{url: _} = input_options}, groups, _source_url_pattern) do
+  defp build_extra({input, %{url: _} = input_options}, groups, _config) do
     input = to_string(input)
     title = validate_extra_string!(input_options, :title) || input
     url = validate_extra_string!(input_options, :url)
@@ -96,15 +95,15 @@ defmodule ExDoc.Extras do
     }
   end
 
-  defp build_extra({input, input_options}, groups, source_url_pattern) do
+  defp build_extra({input, input_options}, groups, config) do
     input = to_string(input)
 
     id =
       validate_extra_string!(input_options, :filename) ||
         input |> filename_to_title() |> Utils.text_to_id()
 
     source_file = validate_extra_string!(input_options, :source) || input
-    opts = [file: source_file, line: 1]
+    opts = [file: source_file, line: 1, markdown_processor: config.markdown_processor]
 
     {extension, source, ast} =
       case extension_name(input) do
@@ -139,7 +138,7 @@ defmodule ExDoc.Extras do
 
     group = Config.match_extra(groups, input)
     source_path = source_file |> Path.relative_to(File.cwd!()) |> String.replace_leading("./", "")
-    source_url = source_url_pattern.(source_path, 1)
+    source_url = config.source_url_pattern.(source_path, 1)
     search_data = validate_search_data!(input_options[:search_data])
 
     %ExDoc.Extras.Page{

lib/ex_doc/formatter/html/search_data.ex

@@ -81,22 +81,20 @@ defmodule ExDoc.Formatter.HTML.SearchData do
     [intro | headers_sections] =
       Regex.split(~r/(?<!#)###? (?<header>\b.+)/, string, include_captures: true)
 
-    {headers, sections} =
+    sections =
       headers_sections
       |> Enum.chunk_every(2)
-      |> Enum.map(fn [header, section] -> {header, section} end)
-      |> Enum.unzip()
-
-    # Now convert the headers into a single markdown document
-    header_tags =
-      headers
-      |> Enum.join("\n\n")
-      |> ExDoc.Markdown.to_ast()
+      |> Enum.map(fn [header, section] ->
+        # Hardcoded markdown processor because we use it only for header matching
+        opts = [markdown_processor: ExDoc.Markdown.Earmark]
+        [{tag, attrs, content, meta}] = ExDoc.Markdown.to_ast(header, opts)
+        {tag, [section: section] ++ attrs, content, meta}
+      end)
       |> ExDoc.DocAST.add_ids_to_headers([:h2, :h3], prefix)
-
-    sections =
-      Enum.zip_with(header_tags, sections, fn {_, attrs, inner, _}, section ->
-        {ExDoc.DocAST.text(inner), Keyword.fetch!(attrs, :id), clean_markdown(section)}
+      |> Enum.map(fn {_, attrs, inner, _} ->
+        id = Keyword.fetch!(attrs, :id)
+        section = Keyword.fetch!(attrs, :section)
+        {ExDoc.DocAST.text(inner), id, clean_markdown(section)}
       end)
 
     {clean_markdown(intro), sections}

lib/ex_doc/language/erlang.ex

@@ -173,15 +173,17 @@ defmodule ExDoc.Language.Erlang do
         ## We try to parse the equiv in order to link to the target
         with {:ok, toks, _} <- :erl_scan.string(:unicode.characters_to_list(equiv <> ".")),
              {:ok, [{:call, _, {:atom, _, func}, args}]} <- :erl_parse.parse_exprs(toks) do
-          "Equivalent to [`#{equiv}`](`#{prefix}#{func}/#{length(args)}`)."
+          equivalent_to(
+            {:a, [href: "`#{prefix}#{func}/#{length(args)}`"],
+             [{:code, [class: "inline"], [equiv], %{}}], %{}}
+          )
         else
           {:ok, [{:op, _, :/, {:atom, _, _}, {:integer, _, _}}]} ->
-            "Equivalent to `#{prefix}#{equiv}`."
+            equivalent_to({:code, [class: "inline"], ["#{prefix}#{equiv}"], %{}})
 
           _ ->
-            "Equivalent to `#{equiv}`."
+            equivalent_to({:code, [class: "inline"], [equiv], %{}})
         end
-        |> ExDoc.DocAST.parse!("text/markdown")
 
       equiv ->
         ExDoc.warn("invalid equiv #{inspect(equiv)}",
@@ -194,6 +196,10 @@ defmodule ExDoc.Language.Erlang do
     end
   end
 
+  defp equivalent_to(node) do
+    [{:p, [], ["Equivalent to ", node, "."], %{}}]
+  end
+
   @impl true
   def autolink_doc(ast, %Autolink{} = config) do
     true = config.language == __MODULE__

lib/ex_doc/markdown.ex

@@ -23,59 +23,32 @@ defmodule ExDoc.Markdown do
   """
   @callback available?() :: boolean()
 
-  @markdown_processors [
-    ExDoc.Markdown.Earmark
-  ]
-
-  @markdown_processor_key :markdown_processor
-
   @doc """
   Converts the given markdown document to HTML AST.
-  """
-  def to_ast(text, opts \\ []) when is_binary(text) do
-    {processor, options} = get_markdown_processor()
-    processor.to_ast(text, options |> Keyword.merge(opts))
-  end
 
-  @doc """
-  Gets the current markdown processor set globally.
-  """
-  def get_markdown_processor do
-    case Application.fetch_env(:ex_doc, @markdown_processor_key) do
-      {:ok, {processor, options}} ->
-        {processor, options}
+  ## Options
 
-      :error ->
-        processor = find_markdown_processor() || raise_no_markdown_processor()
-        put_markdown_processor({processor, []})
-        {processor, []}
-    end
-  end
+    * `:markdown_processor` - The markdown processor to use,
+      either as a module or a `{module, keyword}` tuple
 
-  @doc """
-  Changes the markdown processor globally.
+  All other options are passed through to the markdown processor.
   """
-  def put_markdown_processor(processor) when is_atom(processor) do
-    put_markdown_processor({processor, []})
-  end
+  def to_ast(text, opts \\ []) when is_binary(text) do
+    {processor_pair, options} = Keyword.pop!(opts, :markdown_processor)
 
-  def put_markdown_processor({processor, options}) do
-    Application.put_env(:ex_doc, @markdown_processor_key, {processor, options})
-  end
+    {processor, options} =
+      case processor_pair do
+        {processor, processor_options} when is_atom(processor) and is_list(processor_options) ->
+          {processor, Keyword.merge(processor_options, options)}
 
-  defp find_markdown_processor do
-    Enum.find(@markdown_processors, fn module ->
-      Code.ensure_loaded?(module) && module.available?()
-    end)
-  end
+        processor when is_atom(processor) and processor != nil ->
+          {processor, options}
 
-  defp raise_no_markdown_processor do
-    raise """
-    Could not find a markdown processor to be used by ex_doc.
-    You can either:
+        _ ->
+          raise ArgumentError,
+                ":markdown_processor must be either `Mod` or `{Mod, options}`, got: #{inspect(processor_pair)}"
+      end
 
-    * Add {:earmark, ">= 0.0.0"} to your mix.exs deps
-      to use an Elixir-based markdown processor
-    """
+    processor.to_ast(text, options)
   end
 end

lib/ex_doc/retriever.ex

@@ -130,12 +130,14 @@ defmodule ExDoc.Retriever do
     }
 
     {doc_line, doc_file, format, source_doc, doc_ast, metadata} =
-      get_module_docs(module_data, source)
+      get_module_docs(module_data, source, config)
 
     group_for_doc = config.group_for_doc
     annotations_for_docs = config.annotations_for_docs
 
-    {docs, nodes_groups} = get_docs(module_data, source, group_for_doc, annotations_for_docs)
+    {docs, nodes_groups} =
+      get_docs(module_data, source, group_for_doc, annotations_for_docs, config)
+
     docs = ExDoc.Utils.natural_sort_by(docs, &"#{&1.name}/#{&1.arity}")
 
     moduledoc_groups = Map.get(metadata, :groups, [])
@@ -144,7 +146,8 @@ defmodule ExDoc.Retriever do
       get_docs_groups(
         moduledoc_groups ++ config.docs_groups ++ module_data.default_groups,
         nodes_groups,
-        docs
+        docs,
+        config
       )
 
     metadata = Map.put(metadata, :kind, module_data.type)
@@ -188,29 +191,29 @@ defmodule ExDoc.Retriever do
 
   # Helpers
 
-  defp get_module_docs(module_data, source) do
+  defp get_module_docs(module_data, source, config) do
     {:docs_v1, anno, _, format, moduledoc, metadata, _} = module_data.docs
     doc_file = anno_file(anno, source)
     doc_line = anno_line(anno)
-    options = [file: doc_file, line: doc_line + 1]
+    options = [file: doc_file, line: doc_line + 1, markdown_processor: config.markdown_processor]
     {doc_line, doc_file, format, moduledoc, doc_ast(format, moduledoc, options), metadata}
   end
 
-  defp get_docs(module_data, source, group_for_doc, annotations_for_docs) do
+  defp get_docs(module_data, source, group_for_doc, annotations_for_docs, config) do
     {:docs_v1, _, _, _, _, _, docs} = module_data.docs
 
     {nodes, groups} =
       for doc <- docs,
           doc_data = module_data.language.doc_data(doc, module_data) do
         {_node, _group} =
-          get_doc(doc, doc_data, module_data, source, group_for_doc, annotations_for_docs)
+          get_doc(doc, doc_data, module_data, source, group_for_doc, annotations_for_docs, config)
       end
       |> Enum.unzip()
 
     {filter_defaults(nodes), groups}
   end
 
-  defp get_doc(doc, doc_data, module_data, source, group_for_doc, annotations_for_docs) do
+  defp get_doc(doc, doc_data, module_data, source, group_for_doc, annotations_for_docs, config) do
     {:docs_v1, _, _, content_type, _, module_metadata, _} = module_data.docs
     {{type, name, arity}, anno, _signature, source_doc, metadata} = doc
     doc_file = anno_file(anno, source)
@@ -231,7 +234,11 @@ defmodule ExDoc.Retriever do
     defaults = get_defaults(name, arity, Map.get(metadata, :defaults, 0))
 
     doc_ast =
-      doc_ast(content_type, source_doc, file: doc_file, line: doc_line + 1) ||
+      doc_ast(content_type, source_doc,
+        file: doc_file,
+        line: doc_line + 1,
+        markdown_processor: config.markdown_processor
+      ) ||
         doc_data.doc_fallback.()
 
     group = normalize_group(group_for_doc.(metadata) || doc_data.default_group)
@@ -276,7 +283,7 @@ defmodule ExDoc.Retriever do
     end)
   end
 
-  defp get_docs_groups(module_groups, nodes_groups, doc_nodes) do
+  defp get_docs_groups(module_groups, nodes_groups, doc_nodes, config) do
     module_groups = Enum.map(module_groups, &normalize_group/1)
 
     nodes_groups_descriptions = Map.new(nodes_groups, &{&1.title, &1.description})
@@ -299,15 +306,15 @@ defmodule ExDoc.Retriever do
               {[], seen}
 
             child_nodes ->
-              group = finalize_group(group, child_nodes, nodes_groups_descriptions)
+              group = finalize_group(group, child_nodes, nodes_groups_descriptions, config)
               {[group], seen}
           end
       end)
 
     docs_groups
   end
 
-  defp finalize_group(group, doc_nodes, description_fallbacks) do
+  defp finalize_group(group, doc_nodes, description_fallbacks, config) do
     description =
       case group.description do
         nil -> Map.get(description_fallbacks, group.title)
@@ -320,7 +327,11 @@ defmodule ExDoc.Retriever do
           nil
 
         text ->
-          doc_ast = doc_ast("text/markdown", %{"en" => text}, [])
+          doc_ast =
+            doc_ast("text/markdown", %{"en" => text},
+              markdown_processor: config.markdown_processor
+            )
+
           sub_id = ExDoc.Utils.text_to_id(group.title)
           normalize_doc_ast(doc_ast, "group-#{sub_id}-")
       end