Skip to content

Display description text in docs groups #2113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Jun 11, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions assets/css/content/general.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand Down
6 changes: 6 additions & 0 deletions formatters/html/dist/html-elixir-BHUPNQFZ.css

Large diffs are not rendered by default.

6 changes: 0 additions & 6 deletions formatters/html/dist/html-elixir-KV3YOVJ3.css

This file was deleted.

6 changes: 0 additions & 6 deletions formatters/html/dist/html-erlang-DQDXQC7W.css

This file was deleted.

6 changes: 6 additions & 0 deletions formatters/html/dist/html-erlang-U4PKJ7EN.css

Large diffs are not rendered by default.

5 changes: 2 additions & 3 deletions lib/ex_doc/formatter/epub/templates.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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 """
Expand Down Expand Up @@ -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
)

Expand Down
15 changes: 10 additions & 5 deletions lib/ex_doc/formatter/epub/templates/module_template.eex
Original file line number Diff line number Diff line change
Expand Up @@ -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 %>
Expand Down
39 changes: 22 additions & 17 deletions lib/ex_doc/formatter/html.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 6 additions & 1 deletion lib/ex_doc/formatter/html/search_data.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
20 changes: 6 additions & 14 deletions lib/ex_doc/formatter/html/templates.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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 """
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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)}"

Expand Down Expand Up @@ -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],
Expand Down
15 changes: 10 additions & 5 deletions lib/ex_doc/formatter/html/templates/module_template.eex
Original file line number Diff line number Diff line change
Expand Up @@ -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 %>
Expand Down
17 changes: 0 additions & 17 deletions lib/ex_doc/group_matcher.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""
Expand Down
19 changes: 14 additions & 5 deletions lib/ex_doc/nodes.ex
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ defmodule ExDoc.ModuleNode do
source_path: nil,
source_url: nil,
docs_groups: [],
docs: [],
typespecs: [],
type: nil,
language: nil,
Expand All @@ -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(),
Expand Down Expand Up @@ -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
Loading