Warn when referencing extras that doesn't exists (#1157)

lib/ex_doc/autolink.ex

@@ -1,5 +1,6 @@
 defmodule ExDoc.Autolink do
   @moduledoc false
+
   # * `:app` - the app that the docs are being generated for. When linking modules they are
   #   checked if they are part of the app and based on that the links are relative or absolute.
   #
@@ -16,6 +17,8 @@ defmodule ExDoc.Autolink do
   #
   # * `:ext` - the extension (`".html"`, "`.xhtml"`, etc)
   #
+  # * `:extras` - list of extras
+  #
   # * `:skip_undefined_reference_warnings_on` - list of modules to skip the warning on
 
   @enforce_keys [:app, :file]
@@ -27,6 +30,7 @@ defmodule ExDoc.Autolink do
     :id,
     :file,
     :line,
+    extras: [],
     ext: ".html",
     skip_undefined_reference_warnings_on: []
   ]
@@ -96,9 +100,15 @@ defmodule ExDoc.Autolink do
          true <- is_binary(uri.path),
          true <- uri.path == Path.basename(uri.path),
          ".md" <- Path.extname(uri.path) do
-      without_ext = String.trim_trailing(uri.path, ".md")
-      fragment = (uri.fragment && "#" <> uri.fragment) || ""
-      HTML.text_to_id(without_ext) <> config.ext <> fragment
+      if uri.path in config.extras do
+        without_ext = String.trim_trailing(uri.path, ".md")
+        fragment = (uri.fragment && "#" <> uri.fragment) || ""
+        HTML.text_to_id(without_ext) <> config.ext <> fragment
+      else
+        message = "documentation references file `#{uri.path}` but it doesn't exists"
+        warn(message, config.file, config.line, config.id)
+        nil
+      end
     else
       _ -> nil
     end
@@ -468,6 +478,10 @@ defmodule ExDoc.Autolink do
       "documentation references #{kind} #{inspect(module)}.#{name}/#{arity}" <>
         " but it is undefined or private"
 
+    warn(message, file, line, id)
+  end
+
+  defp warn(message, file, line, id) do
     warning = IO.ANSI.format([:yellow, "warning: ", :reset])
 
     stacktrace =

lib/ex_doc/formatter/html.ex

@@ -71,6 +71,7 @@ defmodule ExDoc.Formatter.HTML do
         app: config.app,
         current_module: node.module,
         ext: ext,
+        extras: extra_paths(config),
         skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on,
         module_id: node.id,
         file: node.source_path,
@@ -286,6 +287,7 @@ defmodule ExDoc.Formatter.HTML do
       app: config.app,
       file: input,
       ext: ext,
+      extras: extra_paths(config),
       skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on
     ]
 
@@ -476,4 +478,14 @@ defmodule ExDoc.Formatter.HTML do
       config
     end
   end
+
+  defp extra_paths(config) do
+    Enum.map(config.extras, fn
+      path when is_binary(path) ->
+        Path.basename(path)
+
+      {path, _} ->
+        path |> Atom.to_string() |> Path.basename()
+    end)
+  end
 end

test/ex_doc/autolink_test.exs

@@ -175,16 +175,18 @@ defmodule ExDoc.AutolinkTest do
     end
 
     test "extras" do
-      assert autolinked({:a, [href: "Foo Bar.md"], ["Foo"]}) == "foo-bar.html"
+      opts = [extras: ["Foo Bar.md"]]
 
-      assert autolinked({:a, [href: "Foo Bar.md"], ["Foo"]}, ext: ".xhtml") ==
+      assert autolinked({:a, [href: "Foo Bar.md"], ["Foo"]}, opts) == "foo-bar.html"
+
+      assert autolinked({:a, [href: "Foo Bar.md"], ["Foo"]}, [ext: ".xhtml"] ++ opts) ==
                "foo-bar.xhtml"
 
-      assert autolinked({:a, [href: "Foo Bar.md#baz"], ["Foo"]}) == "foo-bar.html#baz"
+      assert autolinked({:a, [href: "Foo Bar.md#baz"], ["Foo"]}, opts) == "foo-bar.html#baz"
 
-      assert_unchanged({:a, [href: "https://github.com/foo/bar/blob/master/foo.md"], ["Foo"]})
+      assert_unchanged({:a, [href: "http://example.com/foo.md"], ["Foo"]}, opts)
 
-      assert_unchanged({:a, [href: "#baz"], ["Foo"]})
+      assert_unchanged({:a, [href: "#baz"], ["Foo"]}, opts)
     end
 
     test "other link" do
@@ -340,6 +342,14 @@ defmodule ExDoc.AutolinkTest do
                ~s[t() :: String.bad()]
     end)
 
+    captured =
+      assert_warn(fn ->
+        opts = [extras: []]
+        assert_unchanged({:a, [href: "Foo Bar.md"], ["Foo"]}, opts)
+      end)
+
+    assert captured =~ "documentation references file `Foo Bar.md` but it doesn't exists"
+
     options = [skip_undefined_reference_warnings_on: ["MyModule"], module_id: "MyModule"]
     assert_unchanged(~t"String.upcase/9", options)
   end