Render groups descriptions

Author: lud

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

@@ -25,6 +25,11 @@
     <%= for {group, nodes} <- summary, key = text_to_id(group.title) do %>
       <section id="<%= key %>" class="details-list">
         <h1 class="section-heading"><%=h to_string(group.title) %></h1>
+        <%= if doc = group.rendered_doc do %>
+          <div class="group-description" id="group-description-<%= key %>">
+            <%= H.link_group_headings(doc, key) %>
+          </div>
+        <% end %>
         <div class="<%= key %>-list">
           <%= for node <- nodes, do: H.detail_template(node, module) %>
         </div>

lib/ex_doc/formatter/html.ex

@@ -111,9 +111,15 @@ defmodule ExDoc.Formatter.HTML do
             render_doc(child_node, language, autolink_opts, opts)
           end
 
+        docs_groups =
+          for group <- node.docs_groups do
+            render_doc(group, language, autolink_opts, opts)
+          end
+
         %{
           render_doc(node, language, [{:id, node.id} | autolink_opts], opts)
-          | docs: docs
+          | docs: docs,
+            docs_groups: docs_groups
         }
       end,
       timeout: :infinity

lib/ex_doc/formatter/html/templates.ex

@@ -288,6 +288,10 @@ defmodule ExDoc.Formatter.HTML.Templates do
     link_headings(content, prefix <> "-")
   end
 
+  def link_group_headings(content, key) do
+    link_headings(content, "group-#{key}-")
+  end
+
   templates = [
     detail_template: [:node, :module],
     footer_template: [:config, :node],

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

@@ -51,6 +51,11 @@
       </a>
       <span class="text"><%= group.title %></span>
     </h1>
+    <%= if doc = group.rendered_doc do %>
+      <div class="group-description" id="group-description-<%= key %>">
+        <%= link_group_headings(doc, key) %>
+      </div>
+    <% end %>
     <div class="<%= key %>-list">
       <%= for node <- nodes, do: detail_template(node, module) %>
     </div>

lib/ex_doc/nodes.ex

@@ -26,10 +26,14 @@ defmodule ExDoc.ModuleNode do
             metadata: nil
 
   @typep annotation :: atom()
-  @typep doc_group :: %{
-           title: String.t() | atom(),
-           description: String.t() | nil
-         }
+
+  # TODO: Maybe this is worth its own module
+  @type doc_group :: %{
+          title: String.t() | atom(),
+          description: String.t() | nil,
+          doc: ExDoc.DocAST.t() | nil,
+          rendered_doc: String.t() | nil
+        }
 
   @type t :: %__MODULE__{
           id: String.t(),
@@ -93,7 +97,7 @@ defmodule ExDoc.DocNode do
           signature: String.t(),
           specs: [ExDoc.Language.spec_ast()],
           annotations: [annotation()],
-          group: atom() | nil,
+          group: String.t() | ExDoc.ModuleNode.doc_group() | nil,
           doc_file: String.t(),
           doc_line: non_neg_integer(),
           source_url: String.t() | nil

lib/ex_doc/retriever.ex

@@ -234,6 +234,17 @@ defmodule ExDoc.Retriever do
           {[group], seen}
       end)
 
+    docs_groups =
+      Enum.map(docs_groups, fn group ->
+        doc_ast =
+          case group.description do
+            nil -> nil
+            text -> doc_ast("text/markdown", %{"en" => text}, [])
+          end
+
+        Map.merge(group, %{doc: doc_ast, rendered_doc: nil})
+      end)
+
     # We do not need the full group data in each doc node anymore, only the
     # title.
     doc_nodes = Enum.map(doc_nodes, &Map.put(&1, :group, &1.group.title))

test/ex_doc/formatter/epub/templates_test.exs

@@ -145,6 +145,42 @@ defmodule ExDoc.Formatter.EPUB.TemplatesTest do
       assert content =~ ~r{id="functions".*id="example_1/0"}ms
     end
 
+    test "outputs groups descriptions" do
+      content =
+        get_module_page([CompiledWithDocs],
+          group_for_doc: fn metadata ->
+            if metadata[:purpose] == :example do
+              [
+                title: "Example functions",
+                description: """
+                ### A section heading example
+
+                A content example.
+
+                See `example/1` or `example/2`.
+                A link to `flatten/1`.
+                """
+              ]
+            else
+              "Functions"
+            end
+          end
+        )
+
+      doc = LazyHTML.from_document(content)
+
+      assert Enum.count(doc["div.group-description"]) == 1
+      assert Enum.count(doc["#group-description-example-functions"]) == 1
+      assert Enum.count(doc["#group-description-example-functions h3"]) == 1
+      assert Enum.count(doc["#group-example-functions-a-section-heading-example"]) == 1
+      assert Enum.count(doc["#example-functions .group-description a[href='#example/1']"]) == 1
+      assert Enum.count(doc["#example-functions .group-description a[href='#example/2']"]) == 1
+      assert Enum.count(doc["#example-functions .group-description a[href='#flatten/1']"]) == 1
+
+      assert content =~ ~s[<span class="text">A section heading example</span>]
+      assert content =~ "<p>A content example.</p>"
+    end
+
     test "outputs summaries" do
       content = get_module_page([CompiledWithDocs])
 

test/ex_doc/formatter/html/templates_test.exs

@@ -469,6 +469,42 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
       assert Enum.count(doc["#functions [id='example/2']"]) == 0
     end
 
+    test "outputs groups descriptions", context do
+      content =
+        get_module_page([CompiledWithDocs], context,
+          group_for_doc: fn metadata ->
+            if metadata[:purpose] == :example do
+              [
+                title: "Example functions",
+                description: """
+                ### A section heading example
+
+                A content example.
+
+                See `example/1` or `example/2`.
+                A link to `flatten/1`.
+                """
+              ]
+            else
+              "Functions"
+            end
+          end
+        )
+
+      doc = LazyHTML.from_document(content)
+
+      assert Enum.count(doc["div.group-description"]) == 1
+      assert Enum.count(doc["#group-description-example-functions"]) == 1
+      assert Enum.count(doc["#group-description-example-functions h3"]) == 1
+      assert Enum.count(doc["#group-example-functions-a-section-heading-example"]) == 1
+      assert Enum.count(doc["#example-functions .group-description a[href='#example/1']"]) == 1
+      assert Enum.count(doc["#example-functions .group-description a[href='#example/2']"]) == 1
+      assert Enum.count(doc["#example-functions .group-description a[href='#flatten/1']"]) == 1
+
+      assert content =~ ~s[<span class="text">A section heading example</span>]
+      assert content =~ "<p>A content example.</p>"
+    end
+
     test "outputs deprecation information", context do
       content = get_module_page([CompiledWithDocs], context)