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],

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

@@ -31,28 +31,33 @@
   <% end %>
 </div>
 
-<%= if summary != [] do %>
+<%= if module.docs_groups != [] do %>
   <section id="summary" class="details-list">
     <h1 class="section-heading">
       <a class="hover-link" href="#summary">
         <i class="ri-link-m" aria-hidden="true"></i>
       </a>
       <span class="text">Summary</span>
     </h1>
-    <%= for {name, nodes} <- summary, do: summary_template(name, nodes) %>
+    <%= for group <- module.docs_groups, do: 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">
       <a class="hover-link" href="#<%= key %>">
         <i class="ri-link-m" aria-hidden="true"></i>
       </a>
-      <span class="text"><%= name %></span>
+      <span class="text"><%= group.title %></span>
     </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: detail_template(node, module) %>
+      <%= for node <- group.docs, do: detail_template(node, module) %>
     </div>
   </section>
 <% end %>

lib/ex_doc/formatter/html.ex

@@ -14,23 +14,6 @@ defmodule ExDoc.GroupMatcher do
     Enum.find_index(groups, fn {k, _v} -> k == group end) || -1
   end
 
-  @doc """
-  Group the following entries and while preserving the order in `groups`.
-  """
-  def group_by(groups, entries, by) do
-    entries = Enum.group_by(entries, by)
-
-    {groups, leftovers} =
-      Enum.flat_map_reduce(groups, entries, fn group, grouped_nodes ->
-        case Map.pop(grouped_nodes, group, []) do
-          {[], grouped_nodes} -> {[], grouped_nodes}
-          {entries, grouped_nodes} -> {[{group, entries}], grouped_nodes}
-        end
-      end)
-
-    groups ++ Enum.sort(leftovers)
-  end
-
   @doc """
   Finds a matching group for the given module name, id, and metadata.
   """

lib/ex_doc/formatter/html/search_data.ex

@@ -17,7 +17,6 @@ defmodule ExDoc.ModuleNode do
             source_path: nil,
             source_url: nil,
             docs_groups: [],
-            docs: [],
             typespecs: [],
             type: nil,
             language: nil,
@@ -41,8 +40,7 @@ defmodule ExDoc.ModuleNode do
           moduledoc_file: String.t(),
           source_path: String.t() | nil,
           source_url: String.t() | nil,
-          docs_groups: [atom()],
-          docs: [ExDoc.DocNode.t()],
+          docs_groups: [ExDoc.DocGroupNode.t()],
           typespecs: [ExDoc.DocNode.t()],
           type: atom(),
           language: module(),
@@ -83,11 +81,22 @@ defmodule ExDoc.DocNode do
           source_doc: term() | nil,
           type: atom(),
           signature: String.t(),
-          specs: [ExDoc.Language.spec_ast()],
+          specs: [ExDoc.Language.spec_ast() | String.t()],
           annotations: [annotation()],
-          group: atom() | nil,
+          group: String.t() | nil,
           doc_file: String.t(),
           doc_line: non_neg_integer(),
           source_url: String.t() | nil
         }
 end
+
+defmodule ExDoc.DocGroupNode do
+  defstruct title: nil, description: nil, doc: nil, docs: []
+
+  @type t :: %__MODULE__{
+          title: String.t() | atom(),
+          description: String.t() | nil,
+          doc: ExDoc.DocAST.t() | nil,
+          docs: [ExDoc.DocNode.t()]
+        }
+end