Decouple api reference from extras

Author: josevalim

lib/ex_doc/formatter/epub.ex

@@ -63,7 +63,7 @@ defmodule ExDoc.Formatter.EPUB do
   defp generate_extras(config) do
     for {_title, extras} <- config.extras,
         node <- extras,
-        not is_map_key(node, :url) and node.extension != ".cheatmd" do
+        not is_map_key(node, :url) and node.type != :cheatmd do
       output = "#{config.output}/OEBPS/#{node.id}.xhtml"
       html = Templates.extra_template(config, node)
 

lib/ex_doc/formatter/html.ex

@@ -32,18 +32,11 @@ defmodule ExDoc.Formatter.HTML do
       tasks: filter_list(:task, project_nodes)
     }
 
-    # TODO: api reference should not be treated as an extra
-    extras =
-      if config.api_reference do
-        [build_api_reference(nodes_map, config) | extras]
-      else
-        extras
-      end
-
     all_files =
       search_data ++
         static_files ++
         generate_sidebar_items(nodes_map, extras, config) ++
+        generate_api_reference(nodes_map, config) ++
         generate_extras(extras, config) ++
         generate_favicon(@assets_dir, config) ++
         generate_logo(@assets_dir, config) ++
@@ -185,7 +178,7 @@ defmodule ExDoc.Formatter.HTML do
   end
 
   defp generate_sidebar_items(nodes_map, extras, config) do
-    content = Templates.create_sidebar_items(nodes_map, extras)
+    content = Templates.create_sidebar_items(config, nodes_map, extras)
 
     path = "dist/sidebar_items-#{digest(content)}.js"
     File.write!(Path.join(config.output, path), content)
@@ -221,8 +214,7 @@ defmodule ExDoc.Formatter.HTML do
           next: next && %{path: "#{next.id}.html", title: next.title}
         }
 
-        extension = node.source_path && Path.extname(node.source_path)
-        html = Templates.extra_template(config, node, extra_type(extension), refs)
+        html = Templates.extra_template(config, node, refs)
 
         if File.regular?(output) do
           Utils.warn("file #{Path.relative_to_cwd(output)} already exists", [])
@@ -307,24 +299,23 @@ defmodule ExDoc.Formatter.HTML do
     ]
   end
 
-  defp build_api_reference(nodes_map, config) do
-    api_reference = Templates.api_reference_template(nodes_map)
+  defp generate_api_reference(_nodes_map, %{api_reference: false}) do
+    []
+  end
 
-    title_content =
-      ~s{API Reference <small class="app-vsn">#{config.project} v#{config.version}</small>}
+  defp generate_api_reference(nodes_map, config) do
+    filename = "api-reference.html"
+    output = "#{config.output}/#{filename}"
+    config = set_canonical_url(config, filename)
 
-    %{
-      group: nil,
-      id: "api-reference",
-      source_path: nil,
-      source_url: config.source_url,
-      title: "API Reference",
-      title_content: title_content,
-      content: api_reference,
-      headers:
-        if(nodes_map.modules != [], do: [{:h2, "Modules", "modules"}], else: []) ++
-          if(nodes_map.tasks != [], do: [{:h2, "Mix Tasks", "mix-tasks"}], else: [])
-    }
+    html = Templates.api_reference_template(config, nodes_map)
+
+    if File.regular?(output) do
+      Utils.warn("file #{Path.relative_to_cwd(output)} already exists", [])
+    end
+
+    File.write!(output, html)
+    [filename]
   end
 
   @doc """
@@ -441,16 +432,15 @@ defmodule ExDoc.Formatter.HTML do
 
     title_text = title_ast && ExDoc.DocAST.text(title_ast)
     title_html = title_ast && ExDoc.DocAST.to_string(title_ast)
-
-    group = GroupMatcher.match_extra(groups, input)
     title = input_options[:title] || title_text || filename_to_title(input)
 
+    group = GroupMatcher.match_extra(groups, input)
     source_path = source_file |> Path.relative_to(File.cwd!()) |> String.replace_leading("./", "")
     source_url = source_url_pattern.(source_path, 1)
     search_data = normalize_search_data!(input_options[:search_data])
 
     %{
-      extension: extension,
+      type: extra_type(extension),
       source: source,
       group: group,
       id: id,
@@ -459,9 +449,7 @@ defmodule ExDoc.Formatter.HTML do
       source_url: source_url,
       search_data: search_data,
       title: title,
-      title_content: title_html || title,
-      # Remove this field when API reference is no longer treated as an extra
-      headers: ExDoc.DocAST.extract_headers_with_ids(ast, [:h2])
+      title_content: title_html || title
     }
   end
 

lib/ex_doc/formatter/html/templates.ex

@@ -46,16 +46,26 @@ defmodule ExDoc.Formatter.HTML.Templates do
   @doc """
   Create a JS object which holds all the items displayed in the sidebar area
   """
-  def create_sidebar_items(nodes_map, extras) do
+  def create_sidebar_items(config, nodes_map, extras) do
     nodes =
       nodes_map
       |> Enum.map(&sidebar_module/1)
       |> Map.new()
-      |> Map.put(:extras, sidebar_extras(extras))
+      |> Map.put(:extras, api_reference(config, nodes_map) ++ sidebar_extras(extras))
 
     ["sidebarNodes=" | ExDoc.Utils.to_json(nodes)]
   end
 
+  defp api_reference(%{api_reference: false}, _nodes_map), do: []
+
+  defp api_reference(_config, nodes_map) do
+    headers =
+      if(nodes_map.modules != [], do: [%{id: "Modules", anchor: "modules"}], else: []) ++
+        if(nodes_map.tasks != [], do: [%{id: "Mix Tasks", anchor: "mix-tasks"}], else: [])
+
+    [%{id: "api-reference", title: "API Reference", group: "", headers: headers}]
+  end
+
   defp sidebar_extras(extras) do
     for extra <- extras do
       %{id: id, title: title, group: group} = extra
@@ -73,41 +83,41 @@ defmodule ExDoc.Formatter.HTML.Templates do
             end)
 
           item
-          |> Map.put(:headers, headers_to_id_and_anchors(extra.headers))
+          |> Map.put(:headers, headers(extra.doc))
           |> Map.put(:searchData, search_data)
 
         %{url: url} when is_binary(url) ->
           Map.put(item, :url, url)
 
         _ ->
-          Map.put(item, :headers, headers_to_id_and_anchors(extra.headers))
+          Map.put(item, :headers, headers(extra.doc))
       end
     end
   end
 
   defp sidebar_module({id, modules}) do
     modules =
       for module <- modules do
-        extra =
+        groups =
           module
           |> module_summary()
           |> case do
             [] -> []
             entries -> [nodeGroups: Enum.map(entries, &sidebar_entries/1)]
           end
 
-        sections = module_sections(module)
-
-        deprecated? = not is_nil(module.deprecated)
-
         pairs =
           for key <- [:id, :title, :nested_title, :nested_context],
               value = Map.get(module, key),
               do: {key, value}
 
-        pairs = [{:deprecated, deprecated?} | pairs]
+        others = [
+          deprecated: not is_nil(module.deprecated),
+          sections: headers(module.doc || []),
+          group: to_string(module.group)
+        ]
 
-        Map.new([group: to_string(module.group)] ++ extra ++ pairs ++ sections)
+        Map.new(groups ++ pairs ++ others)
       end
 
     {id, modules}
@@ -135,17 +145,10 @@ defmodule ExDoc.Formatter.HTML.Templates do
     %{key: text_to_id(group), name: group, nodes: nodes}
   end
 
-  defp module_sections(module) do
-    sections =
-      (module.doc || [])
-      |> ExDoc.DocAST.extract_headers_with_ids([:h2])
-      |> headers_to_id_and_anchors()
-
-    [sections: sections]
-  end
-
-  defp headers_to_id_and_anchors(headers) do
-    Enum.map(headers, fn {:h2, text, anchor} ->
+  defp headers(doc) do
+    doc
+    |> ExDoc.DocAST.extract_headers_with_ids([:h2])
+    |> Enum.map(fn {:h2, text, anchor} ->
       %{id: text, anchor: anchor}
     end)
   end
@@ -219,13 +222,13 @@ defmodule ExDoc.Formatter.HTML.Templates do
 
   templates = [
     detail_template: [:node, :module],
-    footer_template: [:config, :node],
+    footer_template: [:config, :source_path],
     head_template: [:config, :title, :noindex],
     module_template: [:config, :module, :summary],
     not_found_template: [:config],
     api_reference_entry_template: [:module_node],
-    api_reference_template: [:nodes_map],
-    extra_template: [:config, :node, :type, :refs],
+    api_reference_template: [:config, :nodes_map],
+    extra_template: [:config, :node, :refs],
     search_template: [:config],
     sidebar_template: [:config, :type],
     summary_template: [:name, :nodes],

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

@@ -1,21 +1,38 @@
-<%= if nodes_map.modules != [] do %>
-  <section class="details-list">
-    <h2 id="modules" class="section-heading">Modules</h2>
-    <div class="summary">
-      <%= for module_node <- Enum.sort_by(nodes_map.modules, & &1.id) do
-        api_reference_entry_template(module_node)
-      end %>
-    </div>
-  </section>
-<% end %>
+<%= head_template(config, "API Reference", false) %>
+<%= sidebar_template(config, :extra) %>
 
-<%= if nodes_map.tasks != [] do %>
-  <section class="details-list">
-    <h2 id="tasks" class="section-heading">Mix Tasks</h2>
-    <div class="summary">
-      <%= for task_node <- nodes_map.tasks do
-        api_reference_entry_template(task_node)
-      end %>
-    </div>
-  </section>
-<% end %>
+<div id="top-content">
+  <div class="heading-with-actions top-heading">
+    <h1>API Reference <small class="app-vsn"><%= config.project %> v#<%= config.version %></small></h1>
+    <%= if config.source_url do %>
+      <a href="<%= config.source_url %>" title="View Source" class="icon-action" rel="help">
+        <i class="ri-code-s-slash-line" aria-hidden="true"></i>
+        <span class="sr-only">View Source</span>
+      </a>
+    <% end %>
+  </div>
+
+  <%= if nodes_map.modules != [] do %>
+    <section class="details-list">
+      <h2 id="modules" class="section-heading">Modules</h2>
+      <div class="summary">
+        <%= for module_node <- Enum.sort_by(nodes_map.modules, & &1.id) do
+          api_reference_entry_template(module_node)
+        end %>
+      </div>
+    </section>
+  <% end %>
+
+  <%= if nodes_map.tasks != [] do %>
+    <section class="details-list">
+      <h2 id="tasks" class="section-heading">Mix Tasks</h2>
+      <div class="summary">
+        <%= for task_node <- nodes_map.tasks do
+          api_reference_entry_template(task_node)
+        end %>
+      </div>
+    </section>
+  <% end %>
+</div>
+
+<%= footer_template(config, nil) %>

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

@@ -1,10 +1,10 @@
 <%= head_template(config, node.title, false) %>
-<%= sidebar_template(config, type) %>
+<%= sidebar_template(config, node.type) %>
 
 <div id="top-content">
   <div class="heading-with-actions top-heading">
     <h1><%= node.title_content %></h1>
-    <%= if type == :cheatmd do %>
+    <%= if node.type == :cheatmd do %>
       <button onclick="window.print()" title="Print Cheatsheet" class="icon-action" rel="print">
         <i class="ri-printer-line" aria-hidden="true"></i>
         <span class="sr-only">Print Cheatsheet</span>
@@ -18,15 +18,15 @@
     <% end %>
   </div>
 
-  <%= if type == :livemd do %>
+  <%= if node.type == :livemd do %>
     <div class="livebook-badge-container">
       <a href="#" class="livebook-badge">
         <img src="https://livebook.dev/badge/v1/blue.svg" alt="Run in Livebook" width="150" />
       </a>
     </div>
   <% end %>
 
-  <%= if type == :cheatmd do %>
+  <%= if node.type == :cheatmd do %>
     <%= node.doc |> ExDoc.DocAST.sectionize([:h2, :h3]) |> render_doc() %>
   <% else %>
     <%= node[:content] || render_doc(node.doc) %>
@@ -60,4 +60,4 @@
   </div>
 </div>
 
-<%= footer_template(config, node) %>
+<%= footer_template(config, node.source_path) %>

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

@@ -6,7 +6,7 @@
 
             <a href="https://preview.hex.pm/preview/<%= config.package %>/<%= config.version %>">Hex Preview</a>
 
-            <%= source_path = node && Map.get(node, :source_path); if source_path do %>
+            <%= if source_path do %>
               (<a href="https://preview.hex.pm/preview/<%= config.package %>/<%= config.version %>/show/<%= source_path %>">current file</a>)
             <% end %>
           </span>

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

@@ -57,4 +57,4 @@
   </section>
 <% end %>
 
-<%= footer_template(config, module) %>
+<%= footer_template(config, module.source_path) %>