Add skip_code_autolink_to option (#1759)

Author: viniciusmuller

lib/ex_doc/autolink.ex

@@ -20,6 +20,8 @@ defmodule ExDoc.Autolink do
   # * `:extras` - map of extras
   #
   # * `:skip_undefined_reference_warnings_on` - list of modules to skip the warning on
+  #
+  # * `:skip_code_autolink_to` - list of terms that will be skipped when autolinking (e.g: "PrivateModule")
 
   defstruct [
     :current_module,
@@ -32,7 +34,8 @@ defmodule ExDoc.Autolink do
     deps: [],
     ext: ".html",
     siblings: [],
-    skip_undefined_reference_warnings_on: []
+    skip_undefined_reference_warnings_on: [],
+    skip_code_autolink_to: []
   ]
 
   @hexdocs "https://hexdocs.pm/"

lib/ex_doc/config.ex

@@ -38,6 +38,7 @@ defmodule ExDoc.Config do
             project: nil,
             retriever: ExDoc.Retriever,
             skip_undefined_reference_warnings_on: [],
+            skip_code_autolink_to: [],
             source_beam: nil,
             source_ref: @default_source_ref,
             source_url: nil,
@@ -75,6 +76,7 @@ defmodule ExDoc.Config do
           project: nil | String.t(),
           retriever: atom(),
           skip_undefined_reference_warnings_on: [String.t()],
+          skip_code_autolink_to: [String.t()],
           source_beam: nil | String.t(),
           source_ref: nil | String.t(),
           source_url: nil | String.t(),

lib/ex_doc/formatter/html.ex

@@ -70,7 +70,8 @@ defmodule ExDoc.Formatter.HTML do
       deps: config.deps,
       ext: ext,
       extras: extra_paths(config),
-      skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on
+      skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on,
+      skip_code_autolink_to: config.skip_code_autolink_to
     ]
 
     project_nodes
@@ -375,7 +376,8 @@ defmodule ExDoc.Formatter.HTML do
       deps: config.deps,
       ext: ext,
       extras: extra_paths(config),
-      skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on
+      skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on,
+      skip_code_autolink_to: config.skip_code_autolink_to
     ]
 
     extras =

lib/ex_doc/language/elixir.ex

@@ -559,6 +559,14 @@ defmodule ExDoc.Language.Elixir do
   end
 
   defp url(string, mode, config) do
+    if Enum.any?(config.skip_code_autolink_to, &(&1 == string)) do
+      nil
+    else
+      parse_url(string, mode, config)
+    end
+  end
+
+  defp parse_url(string, mode, config) do
     case Regex.run(~r{^(.+)/(\d+)$}, string) do
       [_, left, right] ->
         with {:ok, arity} <- parse_arity(right) do

lib/mix/tasks/docs.ex

@@ -148,6 +148,12 @@ defmodule Mix.Tasks.Docs do
       skip the warnings, for a given module/function/callback/type (e.g.: `["Foo", "Bar.baz/0"]`)
       or on a given file (e.g.: `["pages/deprecations.md"]`); default: `[]`.
 
+    * `:skip_code_autolink_to` - Similar to `:skip_undefined_reference_warnings_on`, this option
+      controls which terms will be skipped by ExDoc when building documentation.
+      Useful for example if you want to highlight private modules or functions
+      without warnings (e.g.: `["PrivateModule", "PrivateModule.func/1"]`);
+      default: `[]`.
+
     * `:source_beam` - Path to the beam directory; default: mix's compile path.
 
     * `:source_ref` - The branch/commit/tag used for source link inference;

test/ex_doc/language/elixir_test.exs

@@ -381,6 +381,20 @@ defmodule ExDoc.Language.ElixirTest do
                ~s[t() :: <a href="https://hexdocs.pm/elixir/String.html#t:t/0">String.t</a>()]
     end
 
+    test "skips autolinking if requested" do
+      ExDoc.Refs.insert([
+        {{:module, AutolinkTest.Hidden}, :hidden},
+        {{:function, AutolinkTest.Hidden, :foo, 1}, :hidden}
+      ])
+
+      assert_skip_autolink_no_warn("AutolinkTest.Hidden")
+      assert_skip_autolink_no_warn("AutolinkTest.Hidden.foo/1")
+    end
+
+    defp assert_skip_autolink_no_warn(string) do
+      assert_unchanged(~m(`#{string}`), skip_code_autolink_to: [string])
+    end
+
     test "Elixir basic types" do
       assert autolink_spec(quote(do: t() :: atom())) ==
                ~s[t() :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>()]