Safety check before running File.rm_rf! in doc gen

lib/ex_doc/formatter/epub.ex

@@ -10,9 +10,9 @@ defmodule ExDoc.Formatter.EPUB do
   """
   @spec run(list, ExDoc.Config.t()) :: String.t()
   def run(project_nodes, config) when is_map(config) do
+    parent = config.output
     config = normalize_config(config)
-    File.rm_rf!(config.output)
-    File.mkdir_p!(Path.join(config.output, "OEBPS"))
+    setup_output(config, parent)
 
     project_nodes = HTML.render_all(project_nodes, ".xhtml", config, highlight_tag: "samp")
 
@@ -44,6 +44,32 @@ defmodule ExDoc.Formatter.EPUB do
     Path.relative_to_cwd(epub)
   end
 
+  defp setup_output(config, parent) do
+    safety_path = Path.join(parent, ".ex_doc")
+
+    cond do
+      File.exists?(safety_path) ->
+        File.rm_rf!(config.output)
+        mkdir_output!(config.output, parent)
+
+      not File.exists?(parent) ->
+        mkdir_output!(config.output, parent)
+
+      true ->
+        raise """
+        ex_doc cannot output to #{config.output}:
+        Directory already exists and is not managed by ex_doc.
+
+        Try giving an unexisting directory as `--output`.
+        """
+    end
+  end
+
+  defp mkdir_output!(path, parent) do
+    File.mkdir_p!(Path.join(path, "OEBPS"))
+    File.touch!(Path.join(parent, ".ex_doc"))
+  end
+
   defp normalize_config(config) do
     output =
       config.output

lib/ex_doc/formatter/html.ex

@@ -147,20 +147,40 @@ defmodule ExDoc.Formatter.HTML do
   end
 
   defp output_setup(build, config) do
-    if File.exists?(build) do
-      build
-      |> File.read!()
-      |> String.split("\n", trim: true)
-      |> Enum.map(&Path.join(config.output, &1))
-      |> Enum.each(&File.rm/1)
-
-      File.rm(build)
-    else
-      File.rm_rf!(config.output)
-      File.mkdir_p!(config.output)
+    safety_path = Path.join(config.output, ".ex_doc")
+
+    cond do
+      File.exists?(build) ->
+        build
+        |> File.read!()
+        |> String.split("\n", trim: true)
+        |> Enum.map(&Path.join(config.output, &1))
+        |> Enum.each(&File.rm/1)
+
+        File.rm(build)
+
+      File.exists?(safety_path) ->
+        File.rm_rf!(config.output)
+        mkdir_output!(config.output)
+
+      not File.exists?(config.output) ->
+        mkdir_output!(config.output)
+
+      true ->
+        raise """
+        ex_doc cannot output to #{config.output}:
+        Directory already exists and is not managed by ex_doc.
+
+        Try giving an unexisting directory as `--output`.
+        """
     end
   end
 
+  defp mkdir_output!(path) do
+    File.mkdir_p!(path)
+    File.touch!(Path.join(path, ".ex_doc"))
+  end
+
   defp generate_build(files, build) do
     entries = Enum.map(files, &[&1, "\n"])
     File.write!(build, entries)

test/ex_doc/formatter/epub_test.exs

@@ -103,6 +103,18 @@ defmodule ExDoc.Formatter.EPUBTest do
     assert File.regular?(tmp_dir <> "/epub/another_dir/#{doc_config(context)[:project]}.epub")
   end
 
+  test "fails if trying to write to existing directory", context do
+    assert_raise RuntimeError, ~r/Directory already exists and is not managed by ex_doc/, fn ->
+      config = doc_config(context)
+
+      new_output = config[:output] <> "/new-dir"
+      File.mkdir_p!(new_output)
+
+      new_config = Keyword.put(config, :output, new_output)
+      generate_docs(new_config)
+    end
+  end
+
   test "generates an EPUB file with a standardized structure", %{tmp_dir: tmp_dir} = context do
     generate_docs_and_unzip(context, doc_config(context))
 

test/ex_doc/formatter/html/erlang_test.exs

@@ -5,6 +5,12 @@ defmodule ExDoc.Formatter.HTML.ErlangTest do
   @moduletag :otp_eep48
   @moduletag :tmp_dir
 
+  setup %{tmp_dir: tmp_dir} do
+    output = tmp_dir <> "/doc"
+    File.mkdir!(output)
+    File.touch!("#{output}/.ex_doc")
+  end
+
   test "smoke test", c do
     erlc(c, :foo, ~S"""
     %% @doc

test/ex_doc/formatter/html/search_items_test.exs

@@ -4,6 +4,12 @@ defmodule ExDoc.Formatter.HTML.SearchItemsTest do
 
   @moduletag :tmp_dir
 
+  setup %{tmp_dir: tmp_dir} do
+    output = tmp_dir <> "/doc"
+    File.mkdir!(output)
+    File.touch!("#{output}/.ex_doc")
+  end
+
   test "Elixir module", c do
     modules =
       elixirc(c, ~S'''

test/ex_doc/formatter/html_test.exs

@@ -6,6 +6,12 @@ defmodule ExDoc.Formatter.HTMLTest do
 
   @moduletag :tmp_dir
 
+  setup %{tmp_dir: tmp_dir} do
+    output = tmp_dir <> "/html"
+    File.mkdir_p!(output)
+    File.touch!(output <> "/.ex_doc")
+  end
+
   defp read_wildcard!(path) do
     [file] = Path.wildcard(path)
     File.read!(file)
@@ -146,6 +152,18 @@ defmodule ExDoc.Formatter.HTMLTest do
     refute content_module =~ re[:index][:refresh]
   end
 
+  test "fails if trying to write to existing directory", context do
+    assert_raise RuntimeError, ~r/Directory already exists and is not managed by ex_doc/, fn ->
+      config = doc_config(context)
+
+      new_output = config[:output] <> "/new-dir"
+      File.mkdir_p!(new_output)
+
+      new_config = Keyword.put(config, :output, new_output)
+      generate_docs(new_config)
+    end
+  end
+
   test "allows to set the authors of the document", %{tmp_dir: tmp_dir} = context do
     generate_docs(doc_config(context, authors: ["John Doe", "Jane Doe"]))
     content_index = File.read!(tmp_dir <> "/html/api-reference.html")

test/test_helper.exs

@@ -22,6 +22,10 @@ defmodule TestHelper do
   def elixirc(context, filename \\ "nofile", code) do
     dir = context.tmp_dir
 
+    output_dir = context.tmp_dir <> "/html"
+    File.mkdir_p!(output_dir)
+    File.write!(output_dir <> "/.ex_doc", "")
+
     src_path = Path.join([dir, filename])
     src_path |> Path.dirname() |> File.mkdir_p!()
     File.write!(src_path, code)