Group functions based on metadata

assets/js/helpers.js

@@ -6,7 +6,6 @@
 
 import $ from 'jquery'
 import find from 'lodash.find'
-import findKey from 'lodash.findkey'
 
 // Escape a string for use in a regular expression
 export function escapeText (text) {
@@ -20,13 +19,14 @@ export function getModuleType () {
 // Find out if the anchor belongs to either
 // Types, Functions, Macros or Callbacks
 export function findSidebarCategory (items, query) {
+  if (!items) return
+
   for (let item of items) {
-    const res = findKey(item, (value, key) => {
-      const a = find(value, ({anchor}) => anchor === query)
-      return a
+    const res = find(item.nodeGroups, ({nodes}) => {
+      return find(nodes, ({anchor}) => anchor === query)
     })
 
-    if (res) return res
+    if (res) return res.key
   }
 }
 

assets/js/search.js

@@ -32,18 +32,20 @@ function cleaner (element) {
   return !!element
 }
 
-function findNested (elements, parentId, matcher) {
-  return (elements || []).map(function (element) {
+function findNested (elements, parentId, matcher, acc) {
+  return (elements || []).reduce((acc, element) => {
     // Match things like module.func
     var parentMatch = (parentId + '.' + element.id).match(matcher)
     var match = element.id && element.id.match(matcher)
 
-    if (parentMatch || match) {
+    if ((parentMatch || match) && !acc[element.id]) {
       var result = JSON.parse(JSON.stringify(element))
       result.match = match ? highlight(match) : element.id
-      return result
+      acc[result.id] = result
     }
-  }).filter(cleaner)
+
+    return acc
+  }, acc || {})
 }
 
 function pushLevel (levels, searchEntity, name) {
@@ -54,29 +56,35 @@ function pushLevel (levels, searchEntity, name) {
 
 export function findIn (elements, matcher) {
   return elements.map(function (element) {
-    var title = element.title
-    var titleMatch = title && title.match(matcher)
-    var functionMatches = findNested(element.functions, title, matcher)
-    var guardMatches = findNested(element.guards, title, matcher)
-    var callbackMatches = findNested(element.callbacks, title, matcher)
-    var typeMatches = findNested(element.types, title, matcher)
-
-    var result = {
+    let title = element.title
+    let titleMatch = title && title.match(matcher)
+    let result = {
       id: element.id,
       match: titleMatch ? highlight(titleMatch) : element.title
     }
+    let hasMatch = !!titleMatch
+
+    if (element.nodeGroups) {
+      for (let {key, nodes} of element.nodeGroups) {
+        let matches = findNested(nodes, title, matcher, result[key])
+        if (Object.keys(matches).length > 0) {
+          hasMatch = true
+          if (key === 'types' || key === 'callbacks') {
+            result[key] = matches
+          } else {
+            result.functions = matches
+          }
+        }
+      }
+    }
+
+    if (hasMatch) {
+      for (let key in result) {
+        if (key !== 'id' && key !== 'match') {
+          result[key] = Object.values(result[key]).sort((a, b) => a.id.localeCompare(b.id))
+        }
+      }
 
-    if (functionMatches.length > 0) result.functions = functionMatches
-    if (guardMatches.length > 0) result.guards = guardMatches
-    if (callbackMatches.length > 0) result.callbacks = callbackMatches
-    if (typeMatches.length > 0) result.types = typeMatches
-
-    if (titleMatch ||
-        functionMatches.length > 0 ||
-        guardMatches.length > 0 ||
-        callbackMatches.length > 0 ||
-        typeMatches.length > 0
-       ) {
       return result
     }
   }).filter(cleaner)

assets/js/template-helpers/isEmptyNode.js

@@ -1,17 +1,19 @@
 export default function (node, options) {
-  var nodeItems = [
-    node.headers,
-    node.types,
-    node.functions,
-    node.guards,
-    node.callbacks
-  ]
+  if (hasItems(node.headers)) {
+    return options.inverse(this)
+  }
 
-  for (var i = 0; i < nodeItems.length; i++) {
-    if (Array.isArray(nodeItems[i]) && (nodeItems[i].length > 0)) {
-      return options.inverse(this)
+  if (node.nodeGroups) {
+    for (let {nodes} of node.nodeGroups) {
+      if (hasItems(nodes)) {
+        return options.inverse(this)
+      }
     }
   }
 
   return options.fn(this)
 }
+
+function hasItems (items) {
+  return Array.isArray(items) && (items.length > 0)
+}

assets/js/template-helpers/showSummary.js

@@ -1,5 +1,5 @@
 export default function (node, options) {
-  if (node.types || node.functions || node.guards || node.callbacks) {
+  if (node.nodeGroups) {
     return options.fn(this)
   }
 }

assets/js/templates/search-results.handlebars

@@ -10,11 +10,6 @@
         <h3 class="result-id">
           <a href="{{id}}.html">{{{match}}}</a>
         </h3>
-        <ul class="guards">
-          {{#each guards}}
-            <li class="result-elem"><a href="{{../id}}.html#{{{anchor}}}">{{{match}}}</a></li>
-          {{/each}}
-        </ul>
         <ul class="functions">
           {{#each functions}}
             <li class="result-elem"><a href="{{../id}}.html#{{{anchor}}}">{{{match}}}</a></li>

assets/js/templates/sidebar-items.handlebars

@@ -30,54 +30,18 @@
               <a href="{{node.id}}.html#summary">Summary</a>
             </li>
           {{/showSummary}}
-          {{#if node.types}}
+          {{#each node.nodeGroups as |group|}}
             <li class="docs">
-              <a href="{{node.id}}.html#types" class="expand">Types</a>
-              <ul class="types-list deflist">
-                {{#each node.types}}
+              <a href="{{node.id}}.html#{{group.key}}" class="expand">{{group.name}}</a>
+              <ul class="{{group.key}}-list deflist">
+                {{#each group.nodes}}
                   <li>
                     <a href="{{node.id}}.html#{{anchor}}">{{id}}</a>
                   </li>
                 {{/each}}
               </ul>
             </li>
-          {{/if}}
-          {{#if node.guards}}
-            <li class="docs">
-              <a href="{{node.id}}.html#guards" class="expand">Guards</a>
-              <ul class="guards-list deflist">
-                {{#each node.guards}}
-                  <li>
-                    <a href="{{node.id}}.html#{{anchor}}" class="deflink">{{id}}</a>
-                  </li>
-                {{/each}}
-              </ul>
-            </li>
-          {{/if}}
-          {{#if node.functions}}
-            <li class="docs">
-              <a href="{{node.id}}.html#functions" class="expand">Functions</a>
-              <ul class="functions-list deflist">
-                {{#each node.functions}}
-                  <li>
-                    <a href="{{node.id}}.html#{{anchor}}">{{id}}</a>
-                  </li>
-                {{/each}}
-              </ul>
-            </li>
-          {{/if}}
-          {{#if node.callbacks}}
-            <li class="docs">
-              <a href="{{node.id}}.html#callbacks" class="expand">Callbacks</a>
-              <ul class="callbacks-list deflist">
-                {{#each node.callbacks}}
-                  <li>
-                    <a href="{{node.id}}.html#{{anchor}}" class="deflink">{{id}}</a>
-                  </li>
-                {{/each}}
-              </ul>
-            </li>
-          {{/if}}
+          {{/each}}
         {{/isArray}}
       </ul>
     {{/isEmptyNode}}

assets/test/helpers.spec.js

@@ -12,11 +12,15 @@ describe('helpers', () => {
   describe('findSidebarCategory', () => {
     it('finds the correct category', () => {
       const nodes = [{
-        callbacks: [{anchor: 'hello'}],
-        functions: [{anchor: 'world'}]
+        nodeGroups: [
+          {key: 'callbacks', nodes: [{anchor: 'hello'}]},
+          {key: 'functions', nodes: [{anchor: 'world'}]}
+        ]
       }, {
-        callbacks: [{anchor: 'one'}],
-        guards: [{anchor: 'two'}]
+        nodeGroups: [
+          {key: 'callbacks', nodes: [{anchor: 'one'}]},
+          {key: 'examples', nodes: [{anchor: 'two'}]}
+        ]
       }]
 
       expect(helpers.findSidebarCategory(nodes, 'world')).to.be.eql('functions')

assets/test/search.spec.js

@@ -15,20 +15,20 @@ describe('search', () => {
       var nodes = [{
         id: 'id1',
         title: 'hello world',
-        functions: [
-          {id: 'hello world', anchor: 'hello-world'}
+        nodeGroups: [
+          {key: 'functions', nodes: [{id: 'hello world', anchor: 'hello-world'}]}
         ]
       }, {
         id: 'id2',
         title: 'world',
-        functions: [
-          {id: 'hello world', anchor: 'hello-world'}
+        nodeGroups: [
+          {key: 'examples', nodes: [{id: 'hello world', anchor: 'hello-world'}]}
         ]
       }, {
         id: 'world2',
         title: 'world2',
-        functions: [
-          {id: 'world', anchor: 'world'}
+        nodeGroups: [
+          {key: 'functions', nodes: [{id: 'world', anchor: 'world'}]}
         ]
       }]
 
@@ -49,7 +49,13 @@ describe('search', () => {
 
     it('searches for callback matches', () => {
       var nodes = [
-        {id: 'hello', title: 'hello', callbacks: [{id: 'run'}]},
+        {
+          id: 'hello',
+          title: 'hello',
+          nodeGroups: [
+            {key: 'callbacks', nodes: [{id: 'run'}]}
+          ]
+        },
         {id: 'world', title: 'world'}
       ]
 
@@ -62,31 +68,43 @@ describe('search', () => {
       }])
     })
 
-    it('searches for guard matches', () => {
+    it('searches for matches in custom groups', () => {
       var nodes = [
-        {id: 'hello', title: 'hello', guards: [{id: 'run'}]},
+        {
+          id: 'hello',
+          title: 'hello',
+          nodeGroups: [
+            {key: 'examples', nodes: [{id: 'run'}]}
+          ]
+        },
         {id: 'world', title: 'world'}
       ]
 
       expect(search.findIn(nodes, 'run')).to.be.eql([{
         id: 'hello',
         match: 'hello',
-        guards: [
+        functions: [
           {id: 'run', match: '<em>run</em>'}
         ]
       }])
     })
 
     it('searches for nested matches', () => {
       var nodes = [
-        {id: 'hello', title: 'hello', guards: [{id: 'run'}]},
+        {
+          id: 'hello',
+          title: 'hello',
+          nodeGroups: [
+            {key: 'examples', nodes: [{id: 'run'}]}
+          ]
+        },
         {id: 'world', title: 'world'}
       ]
 
       expect(search.findIn(nodes, 'hello.run')).to.be.eql([{
         id: 'hello',
         match: 'hello',
-        guards: [
+        functions: [
           {id: 'run', match: 'run'}
         ]
       }])

lib/ex_doc/config.ex

@@ -26,6 +26,7 @@ defmodule ExDoc.Config do
             formatter: @default_formatter,
             groups_for_extras: [],
             groups_for_modules: [],
+            groups_for_functions: [],
             homepage_url: nil,
             language: "en",
             logo: nil,
@@ -57,6 +58,7 @@ defmodule ExDoc.Config do
           logo: nil | Path.t(),
           main: nil | String.t(),
           groups_for_modules: keyword(),
+          groups_for_functions: keyword((keyword() -> boolean)),
           output: nil | Path.t(),
           project: nil | String.t(),
           retriever: :atom,

lib/ex_doc/formatter/epub/templates.ex

@@ -10,8 +10,8 @@ defmodule ExDoc.Formatter.EPUB.Templates do
   Generate content from the module template for a given `node`
   """
   def module_page(config, module_node) do
-    summary_map = H.module_summary(module_node)
-    module_template(config, module_node, summary_map)
+    summary = H.module_summary(module_node)
+    module_template(config, module_node, summary)
   end
 
   @doc """
@@ -40,7 +40,7 @@ defmodule ExDoc.Formatter.EPUB.Templates do
     :def,
     :module_template,
     Path.expand("templates/module_template.eex", __DIR__),
-    [:config, :module, :summary_map],
+    [:config, :module, :summary],
     trim: true
   )
 

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

@@ -22,7 +22,7 @@
       <% end %>
     <% end %>
     <%= for static_file <- static_files do %>
-      <item id="<%= static_file |> HTML.input_to_title() |> HTML.title_to_id() %>" href="<%= static_file %>" media-type="<%= media_type(Path.extname(static_file)) %>"/>
+      <item id="<%= static_file |> HTML.filename_to_title() |> HTML.text_to_id() %>" href="<%= static_file %>" media-type="<%= media_type(Path.extname(static_file)) %>"/>
     <% end %>
     <%= if config.logo do %>
       <%= if Path.extname(config.logo) == ".png" do %>