Add --warnings-as-errors flag for non-zero exit code

Author: kdawgwilk

lib/ex_doc/application.ex

@@ -17,6 +17,11 @@ defmodule ExDoc.Application do
         match?("makeup_" <> _, Atom.to_string(app)),
         do: Application.ensure_all_started(app)
 
-    Supervisor.start_link([ExDoc.Refs], strategy: :one_for_one)
+    children = [
+      ExDoc.Refs,
+      ExDoc.WarningCounter
+    ]
+
+    Supervisor.start_link(children, strategy: :one_for_one)
   end
 end

lib/ex_doc/cli.ex

@@ -26,14 +26,25 @@ defmodule ExDoc.CLI do
           package: :string,
           proglang: :string,
           source_ref: :string,
-          version: :boolean
+          version: :boolean,
+          warnings_as_errors: :boolean
         ]
       )
 
-    if List.keymember?(opts, :version, 0) do
-      print_version()
-    else
-      generate(args, opts, generator)
+    cond do
+      List.keymember?(opts, :version, 0) ->
+        print_version()
+
+      opts[:warnings_as_errors] == true and ExDoc.WarningCounter.count() > 0 ->
+        IO.puts(
+          :stderr,
+          "Doc generation failed due to warnings while using the --warnings-as-errors option"
+        )
+
+        exit({:shutdown, ExDoc.WarningCounter.count()})
+
+      true ->
+        generate(args, opts, generator)
     end
   end
 
@@ -140,27 +151,28 @@ defmodule ExDoc.CLI do
       ex_doc "Project" "1.0.0" "_build/dev/lib/project/ebin" -c "docs.exs"
 
     Options:
-      PROJECT             Project name
-      VERSION             Version number
-      BEAMS               Path to compiled beam files
-      -n, --canonical     Indicate the preferred URL with rel="canonical" link element
-      -c, --config        Give configuration through a file instead of a command line.
-                          See "Custom config" section below for more information.
-      -f, --formatter     Docs formatter to use (html or epub), default: "html"
-      -p, --homepage-url  URL to link to for the site name
-          --paths         Prepends the given path to Erlang code path. The path might contain a glob
-                          pattern but in that case, remember to quote it: --paths "_build/dev/lib/*/ebin".
-                          This option can be given multiple times
-          --language      Identify the primary language of the documents, its value must be
-                          a valid [BCP 47](https://tools.ietf.org/html/bcp47) language tag, default: "en"
-      -l, --logo          Path to the image logo of the project (only PNG or JPEG accepted)
-                          The image size will be 64x64 and copied to the assets directory
-      -m, --main          The entry-point page in docs, default: "api-reference"
-          --package       Hex package name
-          --source-ref    Branch/commit/tag used for source link inference, default: "master"
-      -u, --source-url    URL to the source code
-      -o, --output        Path to output docs, default: "doc"
-      -v, --version       Print ExDoc version
+      PROJECT                  Project name
+      VERSION                  Version number
+      BEAMS                    Path to compiled beam files
+      -n, --canonical          Indicate the preferred URL with rel="canonical" link element
+      -c, --config             Give configuration through a file instead of a command line.
+                               See "Custom config" section below for more information.
+      -f, --formatter          Docs formatter to use (html or epub), default: "html"
+      -p, --homepage-url       URL to link to for the site name
+          --paths              Prepends the given path to Erlang code path. The path might contain a glob
+                               pattern but in that case, remember to quote it: --paths "_build/dev/lib/*/ebin".
+                               This option can be given multiple times
+          --language           Identify the primary language of the documents, its value must be
+                               a valid [BCP 47](https://tools.ietf.org/html/bcp47) language tag, default: "en"
+      -l, --logo               Path to the image logo of the project (only PNG or JPEG accepted)
+                               The image size will be 64x64 and copied to the assets directory
+      -m, --main               The entry-point page in docs, default: "api-reference"
+          --package            Hex package name
+          --source-ref         Branch/commit/tag used for source link inference, default: "master"
+      -u, --source-url         URL to the source code
+      -o, --output             Path to output docs, default: "doc"
+      -v, --version            Print ExDoc version
+          --warnings-as-errors Exit with non-zero status if doc generation has one or more warnings
 
     ## Custom config
 

lib/ex_doc/config.ex

@@ -43,7 +43,8 @@ defmodule ExDoc.Config do
             version: nil,
             authors: nil,
             skip_undefined_reference_warnings_on: [],
-            package: nil
+            package: nil,
+            warnings_as_errors: false
 
   @type t :: %__MODULE__{
           apps: [atom()],
@@ -78,6 +79,7 @@ defmodule ExDoc.Config do
           version: nil | String.t(),
           authors: nil | [String.t()],
           skip_undefined_reference_warnings_on: [String.t()],
-          package: :atom | nil
+          package: :atom | nil,
+          warnings_as_errors: boolean()
         }
 end

lib/ex_doc/language.ex

@@ -135,6 +135,8 @@ defmodule ExDoc.Language do
   def get(:erlang, _module), do: {:ok, ExDoc.Language.Erlang}
 
   def get(language, module) when is_atom(language) and is_atom(module) do
+    ExDoc.WarningCounter.increment()
+
     IO.warn(
       "skipping module #{module}, reason: unsupported language (#{language})",
       []

lib/ex_doc/markdown/earmark.ex

@@ -52,6 +52,7 @@ defmodule ExDoc.Markdown.Earmark do
   defp print_messages(messages, options) do
     for {severity, line, message} <- messages do
       file = options[:file]
+      ExDoc.WarningCounter.increment()
       IO.warn("#{inspect(__MODULE__)} (#{severity}) #{file}:#{line} #{message}", [])
     end
   end

lib/ex_doc/retriever.ex

@@ -81,6 +81,7 @@ defmodule ExDoc.Retriever do
             docs
 
           {:error, reason} ->
+            ExDoc.WarningCounter.increment()
             IO.warn("skipping module #{inspect(module)}, reason: #{reason}", [])
             false
         end

lib/ex_doc/warning_counter.ex

@@ -0,0 +1,17 @@
+defmodule ExDoc.WarningCounter do
+  @moduledoc false
+
+  use Agent
+
+  def start_link(_opts) do
+    Agent.start_link(fn -> 0 end, name: __MODULE__)
+  end
+
+  def count do
+    Agent.get(__MODULE__, & &1)
+  end
+
+  def increment do
+    Agent.update(__MODULE__, &(&1 + 1))
+  end
+end

lib/mix/tasks/docs.ex

@@ -21,6 +21,8 @@ defmodule Mix.Tasks.Docs do
     * `--language` - Specifies the language to annotate the
       EPUB output in valid [BCP 47](https://tools.ietf.org/html/bcp47)
 
+    * `--warnings-as-errors` - Exits with non-zero exit code if any warnings are found
+
   The command line options have higher precedence than the options
   specified in your `mix.exs` file below.
 
@@ -299,7 +301,8 @@ defmodule Mix.Tasks.Docs do
     canonical: :string,
     formatter: :keep,
     language: :string,
-    output: :string
+    output: :string,
+    warnings_as_errors: :boolean
   ]
 
   @aliases [n: :canonical, f: :formatter, o: :output]
@@ -349,7 +352,17 @@ defmodule Mix.Tasks.Docs do
     for formatter <- get_formatters(options) do
       index = generator.(project, version, Keyword.put(options, :formatter, formatter))
       Mix.shell().info([:green, "View #{inspect(formatter)} docs at #{inspect(index)}"])
-      index
+
+      if options[:warnings_as_errors] == true and ExDoc.WarningCounter.count() > 0 do
+        Mix.shell().info([
+          :red,
+          "Doc generation failed due to warnings while using the --warnings-as-errors option"
+        ])
+
+        exit({:shutdown, ExDoc.WarningCounter.count()})
+      else
+        index
+      end
     end
   end
 

test/ex_doc/cli_test.exs

@@ -23,6 +23,28 @@ defmodule ExDoc.CLITest do
            end) == "ExDoc v#{ExDoc.version()}\n"
   end
 
+  describe "--warnings-as-errors" do
+    test "exits with 0 with no warnings" do
+      assert {"ExDoc", "1.2.3", [_, _, warnings_as_errors: true]} =
+               run(["ExDoc", "1.2.3", @ebin, "--warnings-as-errors"])
+    end
+
+    test "exits with 1 with warnings" do
+      fun = fn ->
+        io =
+          capture_io(:stderr, fn ->
+            assert {"ExDoc", "1.2.3", [_, _, warnings_as_errors: true]} =
+                     run(["ExDoc", "1.2.3", @ebin, "--warnings-as-errors"])
+          end)
+
+        assert io =~
+                 "Doc generation failed due to warnings while using the --warnings-as-errors option\n"
+      end
+
+      assert catch_exit(fun.()) == {:shutdown, 1}
+    end
+  end
+
   test "too many arguments" do
     fun = fn ->
       run(["ExDoc", "1.2.3", "/", "kaboom"])

test/mix/tasks/docs_test.exs

@@ -181,4 +181,13 @@ defmodule Mix.Tasks.DocsTest do
       ] = run([], app: :umbrella, apps_path: "apps/", docs: [ignore_apps: [:foo]])
     end)
   end
+
+  test "accepts warnings_as_errors in :warnings_as_errors" do
+    assert [
+             {"ex_doc", "dev",
+              [formatter: "html", deps: _, apps: _, source_beam: _, warnings_as_errors: true]},
+             {"ex_doc", "dev",
+              [formatter: "epub", deps: _, apps: _, source_beam: _, warnings_as_errors: true]}
+           ] = run([], app: :ex_doc, docs: [warnings_as_errors: true])
+  end
 end