Get rid of the 'extras-' prefix

Author: milmazz

lib/ex_doc/cli.ex

@@ -107,7 +107,7 @@ defmodule ExDoc.CLI do
       -u, --source-url    URL to the source code
           --source-ref    Branch/commit/tag used for source link inference, default: "master"
       -m, --main          The main, entry-point module in docs,
-                          default: "extra-api-reference" when --formatter is "html"
+                          default: "api-reference" when --formatter is "html"
       -p, --homepage-url  URL to link to for the site name
       -e, --extra         Allow users to include additional Markdown files
                           May be given multiple times

lib/ex_doc/formatter/html.ex

@@ -6,7 +6,7 @@ defmodule ExDoc.Formatter.HTML do
   alias ExDoc.Formatter.HTML.Templates
   alias ExDoc.Formatter.HTML.Autolink
 
-  @main "extra-api-reference"
+  @main "api-reference"
 
   @doc """
   Generate HTML documentation for the given modules
@@ -56,7 +56,7 @@ defmodule ExDoc.Formatter.HTML do
 
   defp generate_api_reference(modules, exceptions, protocols, output, config) do
     content = Templates.api_reference_template(config, modules, exceptions, protocols)
-    File.write!("#{output}/extra-api-reference.html", content)
+    File.write!("#{output}/api-reference.html", content)
   end
 
   defp generate_not_found(modules, exceptions, protocols, output, config) do
@@ -100,35 +100,74 @@ defmodule ExDoc.Formatter.HTML do
           generate_extra(&1, output, module_nodes, modules, exceptions, protocols, config)
          end))
       |> Enum.map(&Task.await/1)
-    [{"extra-api-reference", "API Reference", []}|extras]
+    [{"api-reference", "API Reference", []}|extras]
+  end
+
+  defp generate_extra({input_file, output_file_name}, output, module_nodes, modules, exceptions, protocols, config) do
+    title = input_to_title(output_file_name)
+
+    options = %{
+      title: title,
+      output_file_name: title,
+      input: to_string(input_file),
+      output: output
+    }
+
+    create_extra_files(module_nodes, modules, exceptions, protocols, config, options)
   end
 
   defp generate_extra(input, output, module_nodes, modules, exceptions, protocols, config) do
-    file_ext =
-      input
-      |> Path.extname()
-      |> String.downcase()
+    title = input_to_title(input)
+    output_file_name = title_to_filename(title)
+
+    options = %{
+      title: title,
+      output_file_name: output_file_name,
+      input: input,
+      output: output
+    }
 
-    if file_ext in [".md"] do
-      title = Path.rootname(Path.basename(input))
-      file_name = title_to_filename(title)
+    create_extra_files(module_nodes, modules, exceptions, protocols, config, options)
+  end
 
+  defp create_extra_files(module_nodes, modules, exceptions, protocols, config, options) do
+    if valid_extension_name?(options.input) do
       content =
-        input
+        options.input
         |> File.read!()
         |> Autolink.project_doc(module_nodes)
 
-      html = Templates.extra_template(config, title, modules,
+      html = Templates.extra_template(config, options.title, modules,
                                       exceptions, protocols, link_headers(content))
 
-      File.write!("#{output}/#{file_name}.html", html)
-      {file_name, title, extract_headers(content)}
+      output = "#{options.output}/#{options.output_file_name}.html"
+
+      if File.regular? output do
+        IO.puts "warning: file #{Path.basename output} already exists"
+      end
+
+      File.write!(output, html)
+
+      {options.output_file_name, options.title, extract_headers(content)}
     else
       raise ArgumentError, "file format not recognized, allowed format is: .md"
     end
   end
 
-  @h2_regex ~r/^##([^#].*)$/m
+  defp valid_extension_name?(input) do
+    file_ext =
+      input
+      |> Path.extname()
+      |> String.downcase()
+
+      if file_ext in [".md"] do
+        true
+      else
+        false
+      end
+  end
+
+  @h2_regex ~r/^##([^#].*)\n$/m
 
   defp extract_headers(content) do
     @h2_regex
@@ -143,8 +182,12 @@ defmodule ExDoc.Formatter.HTML do
     end)
   end
 
+  defp input_to_title(input) do
+    input |> Path.basename() |> Path.rootname()
+  end
+
   defp title_to_filename(title) do
-    "extra-" <> (title |> String.replace(" ", "-") |> String.downcase)
+    title |> String.replace(" ", "-") |> String.downcase()
   end
 
   defp header_to_id(header) do

lib/ex_doc/formatter/html/templates/not_found_template.eex

@@ -5,7 +5,7 @@
 
 <p>Sorry, but the page you were trying to get to, does not exist. You
 may want to try searching this site using the sidebar or using our
-<a href="extra-api-reference.html" title="API Reference">API Reference</a> page to find what
+<a href="api-reference.html" title="API Reference">API Reference</a> page to find what
 you were looking for.</p>
 
 <%= footer_template(config) %>

lib/mix/tasks/docs.ex

@@ -40,8 +40,8 @@ defmodule Mix.Tasks.Docs do
     Ignored if `:source_url_pattern` is provided; default: master.
 
   * `:main` - main page of the documentation. It may be a module or a
-    generated page, like "Plug" or "extra-api-reference";
-    default: "extra-api-reference" when --formatter is "html".
+    generated page, like "Plug" or "api-reference";
+    default: "api-reference" when --formatter is "html".
 
   * `:logo` - Path to the image logo of the project (only PNG or JPEG accepted)
     The image size will be 64x64 when --formatter is "html".

test/ex_doc/formatter/html_test.exs

@@ -56,7 +56,7 @@ defmodule ExDoc.Formatter.HTMLTest do
     assert File.regular?("#{output_dir}/CompiledWithDocs.Nested.html")
 
     content = File.read!("#{output_dir}/index.html")
-    assert content =~ ~r{<meta http-equiv="refresh" content="0; url=extra-api-reference.html">}
+    assert content =~ ~r{<meta http-equiv="refresh" content="0; url=api-reference.html">}
   end
 
   test "check headers for index.html and module pages" do
@@ -139,14 +139,14 @@ defmodule ExDoc.Formatter.HTMLTest do
     assert content =~ ~s("modules":[])
     assert content =~ ~s("exceptions":[])
     assert content =~ ~s("protocols":[])
-    assert content =~ ~s("extras":[{"id":"extra-api-reference","title":"API Reference","headers":[]},)
-    assert content =~ ~s({"id":"extra-readme","title":"README","headers":[{"id":" Header sample","anchor":"Header-sample"}]})
+    assert content =~ ~s("extras":[{"id":"api-reference","title":"API Reference","headers":[]},)
+    assert content =~ ~s({"id":"readme","title":"README","headers":[{"id":" Header sample","anchor":"Header-sample"}]})
   end
 
   test "run generates the api reference file" do
     generate_docs(doc_config)
 
-    content = File.read!("#{output_dir}/extra-api-reference.html")
+    content = File.read!("#{output_dir}/api-reference.html")
     assert content =~ ~r{<a href="CompiledWithDocs.html">CompiledWithDocs</a>}
     assert content =~ ~r{<p>moduledoc</p>}
     assert content =~ ~r{<a href="CompiledWithDocs.Nested.html">CompiledWithDocs.Nested</a>}
@@ -159,7 +159,7 @@ defmodule ExDoc.Formatter.HTMLTest do
     content = File.read!("#{output_dir}/index.html")
     assert content =~ ~r{<meta http-equiv="refresh" content="0; url=README.html">}
 
-    content = File.read!("#{output_dir}/extra-readme.html")
+    content = File.read!("#{output_dir}/readme.html")
     assert content =~ ~r{<title>README [^<]*</title>}
     assert content =~ ~r{<h2 id="Header-sample"> Header sample</h2>}
     assert content =~ ~r{<a href="RandomError.html"><code>RandomError</code>}
@@ -176,12 +176,12 @@ defmodule ExDoc.Formatter.HTMLTest do
 
   test "run normalizes options" do
     # 1. Check for output dir having trailing "/" stripped
-    # 2. Check for default [main: "extra-api-reference"]
+    # 2. Check for default [main: "api-reference"]
     generate_docs doc_config(output: "#{output_dir}//", main: nil)
 
     content = File.read!("#{output_dir}/index.html")
-    assert content =~ ~r{<meta http-equiv="refresh" content="0; url=extra-api-reference.html">}
-    assert File.regular?("#{output_dir}/extra-api-reference.html")
+    assert content =~ ~r{<meta http-equiv="refresh" content="0; url=api-reference.html">}
+    assert File.regular?("#{output_dir}/api-reference.html")
 
     # 3. main as index is not allowed
     config = doc_config([main: "index"])