refactor: restructure EPUB, HTML, and Markdown output directories

- Updated output directory structure for EPUB, HTML, and Markdown formats to use a consistent `.build` subdirectory.
- Introduced `output_setup` and `generate_build` functions to manage build file generation and cleanup.
- Adjusted file writing logic to ensure proper paths are used for generated files.
- Enhanced test cases to reflect changes in the output directory structure.

Author: yordis

lib/ex_doc/formatter/epub.ex

@@ -11,8 +11,11 @@ defmodule ExDoc.Formatter.EPUB do
   """
   @spec run([ExDoc.ModuleNode.t()], [ExDoc.ModuleNode.t()], ExDoc.Config.t()) :: String.t()
   def run(project_nodes, filtered_modules, config) when is_map(config) do
+    original_output = Path.expand(config.output)
     config = normalize_config(config)
-    File.rm_rf!(config.output)
+    build_dir = Path.join(original_output, ".build/epub")
+    build = Path.join(build_dir, ".build")
+    output_setup(build, config)
     File.mkdir_p!(Path.join(config.output, "OEBPS"))
 
     project_nodes =
@@ -40,12 +43,15 @@ defmodule ExDoc.Formatter.EPUB do
     uuid = "urn:uuid:#{uuid4()}"
     datetime = format_datetime()
 
-    generate_content(config, nodes_map, uuid, datetime, static_files)
-    generate_nav(config, nodes_map)
-    generate_title(config)
-    generate_extras(config)
-    generate_list(config, nodes_map.modules)
-    generate_list(config, nodes_map.tasks)
+    content_files = generate_content(config, nodes_map, uuid, datetime, static_files)
+    nav_files = generate_nav(config, nodes_map)
+    title_files = generate_title(config)
+    extra_files = generate_extras(config)
+    module_files = generate_list(config, nodes_map.modules)
+    task_files = generate_list(config, nodes_map.tasks)
+
+    all_files = List.flatten([content_files, nav_files, title_files, extra_files, module_files, task_files])
+    generate_build(all_files, build)
 
     {:ok, epub} = generate_epub(config.output)
     File.rm_rf!(config.output)
@@ -65,14 +71,16 @@ defmodule ExDoc.Formatter.EPUB do
     for {_title, extras} <- config.extras,
         node <- extras,
         not is_map_key(node, :url) do
-      output = "#{config.output}/OEBPS/#{node.id}.xhtml"
+      filename = "OEBPS/#{node.id}.xhtml"
+      output = "#{config.output}/#{filename}"
       html = Templates.extra_template(config, node)
 
       if File.regular?(output) do
         Utils.warn("file #{Path.relative_to_cwd(output)} already exists", [])
       end
 
       File.write!(output, html)
+      filename
     end
   end
 
@@ -84,7 +92,9 @@ defmodule ExDoc.Formatter.EPUB do
           do: {Path.relative_to(name, "OEBPS"), media_type}
 
     content = Templates.content_template(config, nodes, uuid, datetime, static_files)
-    File.write("#{config.output}/OEBPS/content.opf", content)
+    filename = "OEBPS/content.opf"
+    File.write("#{config.output}/#{filename}", content)
+    [filename]
   end
 
   defp generate_nav(config, nodes) do
@@ -94,12 +104,16 @@ defmodule ExDoc.Formatter.EPUB do
       end)
 
     content = Templates.nav_template(config, nodes)
-    File.write("#{config.output}/OEBPS/nav.xhtml", content)
+    filename = "OEBPS/nav.xhtml"
+    File.write("#{config.output}/#{filename}", content)
+    [filename]
   end
 
   defp generate_title(config) do
     content = Templates.title_template(config)
-    File.write("#{config.output}/OEBPS/title.xhtml", content)
+    filename = "OEBPS/title.xhtml"
+    File.write("#{config.output}/#{filename}", content)
+    [filename]
   end
 
   defp generate_list(config, nodes) do
@@ -126,6 +140,31 @@ defmodule ExDoc.Formatter.EPUB 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)
+    end
+  end
+
+  defp generate_build(files, build) do
+    entries =
+      files
+      |> Enum.uniq()
+      |> Enum.sort()
+      |> Enum.map(&[&1, "\n"])
+
+    File.mkdir_p!(Path.dirname(build))
+    File.write!(build, entries)
+  end
+
   ## Helpers
 
   defp default_assets(config) do
@@ -159,7 +198,9 @@ defmodule ExDoc.Formatter.EPUB do
 
   defp generate_module_page(module_node, config) do
     content = Templates.module_page(config, module_node)
-    File.write("#{config.output}/OEBPS/#{module_node.id}.xhtml", content)
+    filename = "OEBPS/#{module_node.id}.xhtml"
+    File.write("#{config.output}/#{filename}", content)
+    filename
   end
 
   @two_power_16 65536

lib/ex_doc/formatter/html.ex

@@ -15,7 +15,8 @@ defmodule ExDoc.Formatter.HTML do
     config = normalize_config(config)
     config = %{config | output: Path.expand(config.output)}
 
-    build = Path.join(config.output, ".build")
+    build_dir = Path.join(config.output, ".build/html")
+    build = Path.join(build_dir, ".build")
     output_setup(build, config)
 
     project_nodes = Formatter.render_all(project_nodes, filtered_modules, ".html", config, [])
@@ -79,6 +80,7 @@ defmodule ExDoc.Formatter.HTML do
       |> Enum.sort()
       |> Enum.map(&[&1, "\n"])
 
+    File.mkdir_p!(Path.dirname(build))
     File.write!(build, entries)
   end
 

lib/ex_doc/formatter/markdown.ex

@@ -13,7 +13,8 @@ defmodule ExDoc.Formatter.Markdown do
     Utils.unset_warned()
 
     config = normalize_config(config)
-    build = Path.join(config.output, ".build-markdown")
+    build_dir = Path.join(config.output, ".build/markdown")
+    build = Path.join(build_dir, ".build")
     output_setup(build, config)
 
     extras = Formatter.build_extras(config, ".md")
@@ -77,6 +78,7 @@ defmodule ExDoc.Formatter.Markdown do
       |> Enum.sort()
       |> Enum.map(&[&1, "\n"])
 
+    File.mkdir_p!(Path.dirname(build))
     File.write!(build, entries)
   end
 

test/ex_doc/formatter/html_test.exs

@@ -967,7 +967,7 @@ defmodule ExDoc.Formatter.HTMLTest do
       generate_docs(config)
 
       # Verify necessary files in .build
-      content = File.read!(tmp_dir <> "/html/.build")
+      content = File.read!(tmp_dir <> "/html/.build/html/.build")
       assert content =~ ~r(^readme\.html$)m
       assert content =~ ~r(^api-reference\.html$)m
       assert content =~ ~r(^dist/sidebar_items-[\w]{8}\.js$)m
@@ -995,7 +995,7 @@ defmodule ExDoc.Formatter.HTMLTest do
       File.touch!(keep)
       generate_docs(config)
       assert File.exists?(keep)
-      content = File.read!(tmp_dir <> "/html/.build")
+      content = File.read!(tmp_dir <> "/html/.build/html/.build")
       refute content =~ ~r{keep}
     end
   end