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

Draft
wants to merge 8 commits into
base: main
Choose a base branch
from
Draft
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
13 changes: 9 additions & 4 deletions lib/ex_doc/formatter/epub/templates/module_template.eex
Original file line number Diff line number Diff line change
Expand Up @@ -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.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) %>
<%= 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 @@ -93,27 +93,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
15 changes: 8 additions & 7 deletions lib/ex_doc/formatter/html/templates.ex
Original file line number Diff line number Diff line change
Expand Up @@ -115,9 +115,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 @@ -134,7 +134,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 module_sections(%ExDoc.ModuleNode{rendered_doc: nil}), do: [sections: []]
Expand Down Expand Up @@ -167,10 +167,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
|> Enum.map(&%{id: &1, anchor: URI.encode(text_to_id(&1))})
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)}"
Expand Down Expand Up @@ -281,6 +278,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],
Expand Down
13 changes: 9 additions & 4 deletions lib/ex_doc/formatter/html/templates/module_template.eex
Original file line number Diff line number Diff line change
Expand Up @@ -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.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) %>
<%= 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
18 changes: 15 additions & 3 deletions lib/ex_doc/nodes.ex
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ defmodule ExDoc.ModuleNode do
moduledoc_file: String.t(),
source_path: String.t() | nil,
source_url: String.t() | nil,
docs_groups: [atom()],
docs_groups: [ExDoc.DocGroupNode.t()],
docs: [ExDoc.DocNode.t()],
typespecs: [ExDoc.DocNode.t()],
type: atom(),
Expand Down Expand Up @@ -87,11 +87,23 @@ defmodule ExDoc.DocNode do
rendered_doc: String.t() | 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, rendered_doc: nil, docs: []

@type t :: %__MODULE__{
title: String.t() | atom(),
description: String.t() | nil,
doc: ExDoc.DocAST.t() | nil,
rendered_doc: String.t() | nil,
docs: [ExDoc.DocNode.t()]
}
end
99 changes: 90 additions & 9 deletions lib/ex_doc/retriever.ex
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,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}
Expand All @@ -154,8 +165,8 @@ 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,
docs: docs,
doc_format: format,
doc: doc,
source_doc: source_doc,
Expand Down Expand Up @@ -189,13 +200,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
Expand All @@ -222,9 +235,9 @@ defmodule ExDoc.Retriever do
(source_doc && 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)

%ExDoc.DocNode{
doc_node = %ExDoc.DocNode{
id: doc_data.id_key <> nil_or_name(name, arity),
name: name,
arity: arity,
Expand All @@ -238,9 +251,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: []
Expand All @@ -261,6 +276,57 @@ 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("text/markdown", %{"en" => text}, [])
end

%ExDoc.DocGroupNode{
title: group.title,
description: description,
doc: doc_ast,
docs: doc_nodes
}
end

## General helpers

defp nil_or_name(name, arity) do
Expand Down Expand Up @@ -314,4 +380,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
Loading