Display description text in docs groups

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;
 }

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

@@ -18,15 +18,20 @@
     <%= if summary != [] 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 <- summary, do: H.summary_template(group.title, group.docs) %>
       </section>
     <% end %>
 
-    <%= for {name, nodes} <- summary, key = text_to_id(name) do %>
+    <%= for group <- summary, 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 %>

lib/ex_doc/formatter/html.ex

@@ -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

lib/ex_doc/formatter/html/assets.ex

@@ -7,7 +7,7 @@ defmodule ExDoc.Formatter.HTML.Assets do
     |> Path.wildcard()
     |> Enum.map(fn path ->
       Module.put_attribute(__CALLER__.module, :external_resource, path)
-      {Path.basename(path), File.read!(path)}
+      {Path.basename(path), "File.read!(#{path})"}
     end)
   end
 

lib/ex_doc/formatter/html/search_data.ex

@@ -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/html/templates.ex

@@ -123,9 +123,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 +142,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,10 +153,7 @@ 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
+  def module_summary(module_node), do: module_node.docs_groups
 
   defp favicon_path(%{favicon: nil}), do: nil
   defp favicon_path(%{favicon: favicon}), do: "assets/favicon#{Path.extname(favicon)}"

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

@@ -39,20 +39,25 @@
       </a>
       <span class="text">Summary</span>
     </h1>
-    <%= for {name, nodes} <- summary, do: summary_template(name, nodes) %>
+    <%= for group <- summary, do: summary_template(group.title, group.docs) %>
   </section>
 <% end %>
 
-<%= for {name, nodes} <- summary, key = text_to_id(name) do %>
+<%= for group <- summary, 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/group_matcher.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/nodes.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

lib/ex_doc/retriever.ex

@@ -141,7 +141,18 @@ defmodule ExDoc.Retriever do
     group_for_doc = config.group_for_doc
     annotations_for_docs = config.annotations_for_docs
 
-    docs = get_docs(module_data, source, group_for_doc, annotations_for_docs)
+    {docs, nodes_groups} = get_docs(module_data, source, group_for_doc, annotations_for_docs)
+    docs = ExDoc.Utils.natural_sort_by(docs, &"#{&1.name}/#{&1.arity}")
+
+    moduledoc_groups = Map.get(metadata, :groups, [])
+
+    docs_groups =
+      get_docs_groups(
+        moduledoc_groups ++ config.docs_groups ++ module_data.default_groups,
+        nodes_groups,
+        docs
+      )
+
     metadata = Map.put(metadata, :kind, module_data.type)
     group = GroupMatcher.match_module(config.groups_for_modules, module, module_data.id, metadata)
     {nested_title, nested_context} = module_data.nesting_info || {nil, nil}
@@ -155,8 +166,7 @@ defmodule ExDoc.Retriever do
       module: module,
       type: module_data.type,
       deprecated: metadata[:deprecated],
-      docs_groups: config.docs_groups ++ module_data.default_groups,
-      docs: ExDoc.Utils.natural_sort_by(docs, &"#{&1.name}/#{&1.arity}"),
+      docs_groups: docs_groups,
       doc: normalize_doc_ast(doc_ast, "module-"),
       source_doc: source_doc,
       source_format: format,
@@ -195,13 +205,15 @@ defmodule ExDoc.Retriever do
   defp get_docs(module_data, source, group_for_doc, annotations_for_docs) do
     {:docs_v1, _, _, _, _, _, docs} = module_data.docs
 
-    nodes =
+    {nodes, groups} =
       for doc <- docs,
           doc_data = module_data.language.doc_data(doc, module_data) do
-        get_doc(doc, doc_data, module_data, source, group_for_doc, annotations_for_docs)
+        {_node, _group} =
+          get_doc(doc, doc_data, module_data, source, group_for_doc, annotations_for_docs)
       end
+      |> Enum.unzip()
 
-    filter_defaults(nodes)
+    {filter_defaults(nodes), groups}
   end
 
   defp get_doc(doc, doc_data, module_data, source, group_for_doc, annotations_for_docs) do
@@ -228,10 +240,10 @@ defmodule ExDoc.Retriever do
       doc_ast(content_type, source_doc, file: doc_file, line: doc_line + 1) ||
         doc_data.doc_fallback.()
 
-    group = group_for_doc.(metadata) || doc_data.default_group
+    group = normalize_group(group_for_doc.(metadata) || doc_data.default_group)
     id = doc_data.id_key <> nil_or_name(name, arity)
 
-    %ExDoc.DocNode{
+    doc_node = %ExDoc.DocNode{
       id: id,
       name: name,
       arity: arity,
@@ -245,9 +257,11 @@ defmodule ExDoc.Retriever do
       specs: doc_data.specs,
       source_url: source_url,
       type: doc_data.type,
-      group: group,
+      group: group.title,
       annotations: annotations
     }
+
+    {doc_node, group}
   end
 
   defp get_defaults(_name, _arity, 0), do: []
@@ -268,6 +282,62 @@ defmodule ExDoc.Retriever do
     end)
   end
 
+  defp get_docs_groups(module_groups, nodes_groups, doc_nodes) do
+    module_groups = Enum.map(module_groups, &normalize_group/1)
+
+    # Doc nodes already have normalized groups
+    nodes_groups_descriptions = Map.new(nodes_groups, &{&1.title, &1.description})
+
+    normal_groups = module_groups ++ nodes_groups
+    nodes_by_group_title = Enum.group_by(doc_nodes, & &1.group)
+
+    {docs_groups, _} =
+      Enum.flat_map_reduce(normal_groups, %{}, fn
+        group, seen when is_map_key(seen, group.title) ->
+          {[], seen}
+
+        group, seen ->
+          seen = Map.put(seen, group.title, true)
+
+          case Map.get(nodes_by_group_title, group.title, []) do
+            [] ->
+              {[], seen}
+
+            child_nodes ->
+              group = finalize_group(group, child_nodes, nodes_groups_descriptions)
+              {[group], seen}
+          end
+      end)
+
+    docs_groups
+  end
+
+  defp finalize_group(group, doc_nodes, description_fallbacks) do
+    description =
+      case group.description do
+        nil -> Map.get(description_fallbacks, group.title)
+        text -> text
+      end
+
+    doc_ast =
+      case description do
+        nil ->
+          nil
+
+        text ->
+          doc_ast = doc_ast("text/markdown", %{"en" => text}, [])
+          sub_id = ExDoc.Utils.text_to_id(group.title)
+          normalize_doc_ast(doc_ast, "group-#{sub_id}-")
+      end
+
+    %ExDoc.DocGroupNode{
+      title: group.title,
+      description: description,
+      doc: doc_ast,
+      docs: doc_nodes
+    }
+  end
+
   ## General helpers
 
   defp nil_or_name(name, arity) do
@@ -321,4 +391,19 @@ defmodule ExDoc.Retriever do
   defp source_link(%{url_pattern: url_pattern, relative_path: path}, line) do
     url_pattern.(path, line)
   end
+
+  defp normalize_group(group) do
+    case group do
+      %{title: title, description: description}
+      when is_binary(title) and (is_binary(description) or is_nil(description)) ->
+        %{group | title: title, description: description}
+
+      kw when is_list(kw) ->
+        true = Keyword.keyword?(kw)
+        %{title: to_string(Keyword.fetch!(kw, :title)), description: kw[:description]}
+
+      title when is_binary(title) when is_atom(title) ->
+        %{title: to_string(title), description: nil}
+    end
+  end
 end