Display description text in docs groups (#2113)

Author: lud

assets/css/content/general.css

@@ -71,6 +71,10 @@
   margin: 1.5em 0 0.5em;
 }
 
+.content-inner div.group-description {
+  margin: 0 0 3em;
+}
+
 .content-inner h1 small {
   font-weight: 400;
 }

formatters/html/dist/html-elixir-BHUPNQFZ.css

@@ -16,8 +16,7 @@ defmodule ExDoc.Formatter.EPUB.Templates do
   Generate content from the module template for a given `node`
   """
   def module_page(config, module_node) do
-    summary = H.module_summary(module_node)
-    module_template(config, module_node, summary)
+    module_template(config, module_node)
   end
 
   @doc """
@@ -53,7 +52,7 @@ defmodule ExDoc.Formatter.EPUB.Templates do
     :def,
     :module_template,
     Path.expand("templates/module_template.eex", __DIR__),
-    [:config, :module, :summary],
+    [:config, :module],
     trim: true
   )
 

formatters/html/dist/html-elixir-KV3YOVJ3.css

@@ -15,18 +15,23 @@
       </section>
     <% end %>
 
-    <%= if summary != [] do %>
+    <%= if module.docs_groups != [] do %>
       <section id="summary" class="details-list">
         <h1 class="section-heading">Summary</h1>
-        <%= for {name, nodes} <- summary, do: H.summary_template(name, nodes) %>
+        <%= for group <- module.docs_groups, do: H.summary_template(group.title, group.docs) %>
       </section>
     <% end %>
 
-    <%= for {name, nodes} <- summary, key = text_to_id(name) do %>
+    <%= for group <- module.docs_groups, key = text_to_id(group.title) do %>
       <section id="<%= key %>" class="details-list">
-        <h1 class="section-heading"><%=h to_string(name) %></h1>
+        <h1 class="section-heading"><%=h to_string(group.title) %></h1>
+        <%= if doc = group.doc  do %>
+          <div class="group-description" id="group-description-<%= key %>">
+            <%= render_doc(doc) %>
+          </div>
+        <% end %>
         <div class="<%= key %>-list">
-          <%= for node <- nodes, do: H.detail_template(node, module) %>
+          <%= for node <- group.docs, do: H.detail_template(node, module) %>
         </div>
       </section>
     <% end %>

formatters/html/dist/html-erlang-DQDXQC7W.css

@@ -87,27 +87,32 @@ defmodule ExDoc.Formatter.HTML do
             language: language
           ] ++ base
 
-        docs =
-          for child_node <- node.docs do
-            id = id(node, child_node)
-
-            autolink_opts =
-              autolink_opts ++
-                [
-                  id: id,
-                  line: child_node.doc_line,
-                  file: child_node.doc_file,
-                  current_kfa: {child_node.type, child_node.name, child_node.arity}
-                ]
-
-            specs = Enum.map(child_node.specs, &language.autolink_spec(&1, autolink_opts))
-            child_node = %{child_node | specs: specs}
-            render_doc(child_node, language, autolink_opts, opts)
+        docs_groups =
+          for group <- node.docs_groups do
+            docs =
+              for child_node <- group.docs do
+                id = id(node, child_node)
+
+                autolink_opts =
+                  autolink_opts ++
+                    [
+                      id: id,
+                      line: child_node.doc_line,
+                      file: child_node.doc_file,
+                      current_kfa: {child_node.type, child_node.name, child_node.arity}
+                    ]
+
+                specs = Enum.map(child_node.specs, &language.autolink_spec(&1, autolink_opts))
+                child_node = %{child_node | specs: specs}
+                render_doc(child_node, language, autolink_opts, opts)
+              end
+
+            %{render_doc(group, language, autolink_opts, opts) | docs: docs}
           end
 
         %{
           render_doc(node, language, [{:id, node.id} | autolink_opts], opts)
-          | docs: docs
+          | docs_groups: docs_groups
         }
       end,
       timeout: :infinity

formatters/html/dist/html-erlang-U4PKJ7EN.css

@@ -44,7 +44,12 @@ defmodule ExDoc.Formatter.HTML.SearchData do
     page = URI.encode(node.id) <> ".html"
     {intro, sections} = extract_sections(node.source_format, node, "module-")
     module = encode(page, node.title, node.type, intro)
-    docs = Enum.flat_map(node.docs, &node_child(&1, node, page))
+
+    docs =
+      node.docs_groups
+      |> Enum.flat_map(& &1.docs)
+      |> Enum.flat_map(&node_child(&1, node, page))
+
     [module] ++ render_sections(sections, page, node.title, node.type) ++ docs
   end
 

lib/ex_doc/formatter/epub/templates.ex

@@ -16,8 +16,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
   Generate content from the module template for a given `node`
   """
   def module_page(module_node, config) do
-    summary = module_summary(module_node)
-    module_template(config, module_node, summary)
+    module_template(config, module_node)
   end
 
   @doc """
@@ -99,9 +98,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
     modules =
       for module <- modules do
         groups =
-          module
-          |> module_summary()
-          |> case do
+          case module.docs_groups do
             [] -> []
             entries -> [nodeGroups: Enum.map(entries, &sidebar_entries/1)]
           end
@@ -123,9 +120,9 @@ defmodule ExDoc.Formatter.HTML.Templates do
     {id, modules}
   end
 
-  defp sidebar_entries({group, nodes}) do
+  defp sidebar_entries(group) do
     nodes =
-      for node <- nodes do
+      for node <- group.docs do
         id =
           if "struct" in node.annotations do
             node.signature
@@ -142,7 +139,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
         %{id: id, title: node.signature, anchor: URI.encode(node.id), deprecated: deprecated?}
       end
 
-    %{key: text_to_id(group), name: group, nodes: nodes}
+    %{key: text_to_id(group.title), name: group.title, nodes: nodes}
   end
 
   defp headers(doc) do
@@ -153,11 +150,6 @@ defmodule ExDoc.Formatter.HTML.Templates do
     end)
   end
 
-  def module_summary(module_node) do
-    # TODO: Maybe it should be moved to retriever and it already returned grouped metadata
-    ExDoc.GroupMatcher.group_by(module_node.docs_groups, module_node.docs, & &1.group)
-  end
-
   defp favicon_path(%{favicon: nil}), do: nil
   defp favicon_path(%{favicon: favicon}), do: "assets/favicon#{Path.extname(favicon)}"
 
@@ -225,7 +217,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
     detail_template: [:node, :module],
     footer_template: [:config, :source_path],
     head_template: [:config, :title, :noindex],
-    module_template: [:config, :module, :summary],
+    module_template: [:config, :module],
     not_found_template: [:config],
     api_reference_entry_template: [:module_node],
     api_reference_template: [:config, :nodes_map],