Add grouping of modules

Author: LostKobrakai

lib/ex_doc.ex

@@ -42,6 +42,7 @@ defmodule ExDoc do
       language: @default.language,
       logo: nil,
       main: nil,
+      module_groups: [],
       output: @default.output,
       project: nil,
       retriever: @default.retriever,
@@ -70,6 +71,7 @@ defmodule ExDoc do
        language: String.t,
        logo: nil | Path.t,
        main: nil | String.t,
+       module_groups: list(),
        output: nil | Path.t,
        project: nil | String.t,
        retriever: :atom,

lib/ex_doc/formatter/html/templates.ex

@@ -176,9 +176,9 @@ defmodule ExDoc.Formatter.HTML.Templates do
       |> Enum.map_join(",", &sidebar_items_by_type/1)
 
     if items == "" do
-      ~s/{"id":"#{module_node.id}","title":"#{module_node.title}"}/
+      ~s/{"id":"#{module_node.id}","title":"#{module_node.title}","group":"#{module_node.group}"}/
     else
-      ~s/{"id":"#{module_node.id}","title":"#{module_node.title}",#{items}}/
+      ~s/{"id":"#{module_node.id}","title":"#{module_node.title}","group":"#{module_node.group}",#{items}}/
     end
   end
 

lib/ex_doc/retriever.ex

@@ -3,13 +3,15 @@ defmodule ExDoc.ModuleNode do
   Structure that represents a *module*
   """
 
-  defstruct id: nil, title: nil, module: nil, doc: nil, doc_line: nil,
-    docs: [], typespecs: [], source_path: nil, source_url: nil, type: nil
+  defstruct id: nil, title: nil, module: nil, group: nil, doc: nil,
+    doc_line: nil, docs: [], typespecs: [], source_path: nil,
+    source_url: nil, type: nil
 
   @type t :: %__MODULE__{
     id: nil | String.t,
     title: nil | String.t,
     module: nil | String.t,
+    group: nil | String.t,
     docs: list(),
     doc: nil | String.t,
     doc_line: non_neg_integer(),
@@ -115,7 +117,7 @@ defmodule ExDoc.Retriever do
     modules
     |> Enum.map(&get_module(&1, config))
     |> Enum.filter(&(&1))
-    |> Enum.sort(&(&1.id <= &2.id))
+    |> Enum.sort_by(&({&1.group, &1.id}))
   end
 
   defp filename_to_module(name) do
@@ -157,6 +159,7 @@ defmodule ExDoc.Retriever do
   end
 
   defp generate_node(module, type, config) do
+    module_group_patterns = config.module_groups
     source_url  = config.source_url_pattern
     source_path = source_path(module, config)
     source = %{url: source_url, path: source_path}
@@ -171,10 +174,13 @@ defmodule ExDoc.Retriever do
 
     {title, id} = module_title_and_id(module, type)
 
+    module_group = module_group(module, module_group_patterns)
+
     %ExDoc.ModuleNode{
       id: id,
       title: title,
       module: module_info.name,
+      group: module_group,
       type: type,
       docs: docs,
       doc: moduledoc,
@@ -458,6 +464,25 @@ defmodule ExDoc.Retriever do
     {id, id}
   end
 
+  defp module_group(module, group_patterns) do
+    Enum.find_value(group_patterns, fn {group, patterns} ->
+      patterns = List.wrap patterns
+      module_in_patterns(module, patterns) && Atom.to_string(group)
+    end)
+  end
+
+  defp module_in_patterns(module, patterns) do
+    "Elixir." <> module_string = Atom.to_string module
+
+    Enum.any?(patterns, fn pattern ->
+      case pattern do
+        %Regex{} = regex -> Regex.match?(regex, module_string)
+        string when is_binary(string) -> module_string === string
+        atom -> atom === module
+      end
+    end)
+  end
+
   defp module_id(module) do
     case inspect(module) do
       ":" <> inspected -> inspected

test/ex_doc/retriever_test.exs

@@ -5,7 +5,15 @@ defmodule ExDoc.RetrieverTest do
 
   defp docs_from_files(names, url_pattern \\ "http://example.com/%{path}#L%{line}") do
     files  = Enum.map names, fn(n) -> "test/tmp/Elixir.#{n}.beam" end
-    config = %ExDoc.Config{source_url_pattern: url_pattern, source_root: File.cwd!}
+    config = %ExDoc.Config{
+      source_url_pattern: url_pattern,
+      source_root: File.cwd!,
+      module_groups: [
+        "Group Atom": [GroupedExplicitlyAtom],
+        "Group String": ["GroupedExplicitlyString"],
+        "Group Implicit": ~r/GroupedImplicitly.?/
+      ]
+    }
     Retriever.docs_from_files(files, config)
   end
 
@@ -44,6 +52,23 @@ defmodule ExDoc.RetrieverTest do
     assert module_node.module == CompiledWithDocs
   end
 
+  describe "docs_from_files returns the group" do
+    test "atom" do
+      [module_node] = docs_from_files ["GroupedExplicitlyAtom"]
+      assert module_node.group == "Group Atom"
+    end
+
+    test "string" do
+      [module_node] = docs_from_files ["GroupedExplicitlyString"]
+      assert module_node.group == "Group String"
+    end
+
+    test "regex" do
+      [module_node] = docs_from_files ["GroupedImplicitlyRegex"]
+      assert module_node.group == "Group Implicit"
+    end
+  end
+
   test "docs_from_files returns the moduledoc info" do
     [module_node] = docs_from_files ["CompiledWithDocs"]
     assert module_node.doc == "moduledoc\n\n\#\# Example ☃ Unicode > escaping\n    CompiledWithDocs.example\n\n### Example H3 heading\n\nexample\n"

test/fixtures/grouped_explicitly_atom.ex

@@ -0,0 +1,3 @@
+defmodule GroupedExplicitlyAtom do
+  @moduledoc false
+end

test/fixtures/grouped_explicitly_string.ex

@@ -0,0 +1,3 @@
+defmodule GroupedExplicitlyString do
+  @moduledoc false
+end

test/fixtures/grouped_implicitly_regex.ex

@@ -0,0 +1,3 @@
+defmodule GroupedImplicitlyRegex do
+  @moduledoc false
+end