Function and module summaries

lib/ex_doc/html_formatter.ex

@@ -18,6 +18,8 @@ defmodule ExDoc.HTMLFormatter do
  has_readme = config.readme && generate_readme(output)
 
  modules = Autolink.all(modules)
+
+ generate_overview(modules, output, config)
 
  Enum.each [:modules, :records, :protocols], fn(mod_type) ->
  generate_list(mod_type, modules, output, config, has_readme)
@@ -28,6 +30,16 @@ defmodule ExDoc.HTMLFormatter do
  content = Templates.index_template(config)
  File.write("#{output}/index.html", content)
  end
+
+ defp generate_overview(modules, output, config) do
+ content = Templates.overview_template(
+ config,
+ filter_list(:modules, modules),
+ filter_list(:records, modules),
+ filter_list(:protocols, modules)
+ )
+ File.write("#{output}/overview.html", content)
+ end
 
  defp assets do
  [ { templates_path("css/*.css"), "css" },

lib/ex_doc/html_formatter/templates.ex

@@ -50,6 +50,12 @@ defmodule ExDoc.HTMLFormatter.Templates do
  Macro.to_string { name, 0, args }
  end
 
+ # Get the first paragraph of the documentation of a node, if any.
+ defp synopsis(nil), do: nil
+ defp synopsis(doc) do
+ String.split(doc, %r/\n\s*\n/) |> hd
+ end
+
  defp presence([]), do: nil
  defp presence(other), do: other
 
@@ -61,8 +67,10 @@ defmodule ExDoc.HTMLFormatter.Templates do
  templates = [
  index_template: [:config],
  list_template: [:scope, :nodes, :config, :has_readme],
+ overview_template: [:config, :modules, :records, :protocols],
  module_template: [:module, :types, :functions, :macros, :callbacks],
  list_item_template: [:node],
+ overview_entry_template: [:node],
  summary_template: [:node],
  detail_template: [:node, :_module],
  type_detail_template: [:node, :_module],

lib/ex_doc/html_formatter/templates/css/full_list.css

@@ -8,6 +8,7 @@ body {
 
 h1 { padding: 12px 10px; padding-bottom: 0; margin: 0; font-size: 1.4em; }
 h2#readme { padding: 6px 10px; padding-bottom: 0; margin: 0; font-size: 1.1em; }
+h2#overview { padding: 6px 10px; padding-bottom: 0; margin: 0; font-size: 1.1em; }
 .clear { clear: both; }
 #search { position: absolute; right: 5px; top: 9px; padding-left: 24px; }
 #content.insearch #search, #content.insearch #noresults { background: url(data:image/gif;base64,R0lGODlhEAAQAPYAAP///wAAAPr6+pKSkoiIiO7u7sjIyNjY2J6engAAAI6OjsbGxjIyMlJSUuzs7KamppSUlPLy8oKCghwcHLKysqSkpJqamvT09Pj4+KioqM7OzkRERAwMDGBgYN7e3ujo6Ly8vCoqKjY2NkZGRtTU1MTExDw8PE5OTj4+PkhISNDQ0MrKylpaWrS0tOrq6nBwcKysrLi4uLq6ul5eXlxcXGJiYoaGhuDg4H5+fvz8/KKiohgYGCwsLFZWVgQEBFBQUMzMzDg4OFhYWBoaGvDw8NbW1pycnOLi4ubm5kBAQKqqqiQkJCAgIK6urnJyckpKSjQ0NGpqatLS0sDAwCYmJnx8fEJCQlRUVAoKCggICLCwsOTk5ExMTPb29ra2tmZmZmhoaNzc3KCgoBISEiIiIgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH/C05FVFNDQVBFMi4wAwEAAAAh/hpDcmVhdGVkIHdpdGggYWpheGxvYWQuaW5mbwAh+QQJCAAAACwAAAAAEAAQAAAHaIAAgoMgIiYlg4kACxIaACEJCSiKggYMCRselwkpghGJBJEcFgsjJyoAGBmfggcNEx0flBiKDhQFlIoCCA+5lAORFb4AJIihCRbDxQAFChAXw9HSqb60iREZ1omqrIPdJCTe0SWI09GBACH5BAkIAAAALAAAAAAQABAAAAdrgACCgwc0NTeDiYozCQkvOTo9GTmDKy8aFy+NOBA7CTswgywJDTIuEjYFIY0JNYMtKTEFiRU8Pjwygy4ws4owPyCKwsMAJSTEgiQlgsbIAMrO0dKDGMTViREZ14kYGRGK38nHguHEJcvTyIEAIfkECQgAAAAsAAAAABAAEAAAB2iAAIKDAggPg4iJAAMJCRUAJRIqiRGCBI0WQEEJJkWDERkYAAUKEBc4Po1GiKKJHkJDNEeKig4URLS0ICImJZAkuQAhjSi/wQyNKcGDCyMnk8u5rYrTgqDVghgZlYjcACTA1sslvtHRgQAh+QQJCAAAACwAAAAAEAAQAAAHZ4AAgoOEhYaCJSWHgxGDJCQARAtOUoQRGRiFD0kJUYWZhUhKT1OLhR8wBaaFBzQ1NwAlkIszCQkvsbOHL7Y4q4IuEjaqq0ZQD5+GEEsJTDCMmIUhtgk1lo6QFUwJVDKLiYJNUd6/hoEAIfkECQgAAAAsAAAAABAAEAAAB2iAAIKDhIWGgiUlh4MRgyQkjIURGRiGGBmNhJWHm4uen4ICCA+IkIsDCQkVACWmhwSpFqAABQoQF6ALTkWFnYMrVlhWvIKTlSAiJiVVPqlGhJkhqShHV1lCW4cMqSkAR1ofiwsjJyqGgQAh+QQJCAAAACwAAAAAEAAQAAAHZ4AAgoOEhYaCJSWHgxGDJCSMhREZGIYYGY2ElYebi56fhyWQniSKAKKfpaCLFlAPhl0gXYNGEwkhGYREUywag1wJwSkHNDU3D0kJYIMZQwk8MjPBLx9eXwuETVEyAC/BOKsuEjYFhoEAIfkECQgAAAAsAAAAABAAEAAAB2eAAIKDhIWGgiUlh4MRgyQkjIURGRiGGBmNhJWHm4ueICImip6CIQkJKJ4kigynKaqKCyMnKqSEK05StgAGQRxPYZaENqccFgIID4KXmQBhXFkzDgOnFYLNgltaSAAEpxa7BQoQF4aBACH5BAkIAAAALAAAAAAQABAAAAdogACCg4SFggJiPUqCJSWGgkZjCUwZACQkgxGEXAmdT4UYGZqCGWQ+IjKGGIUwPzGPhAc0NTewhDOdL7Ykji+dOLuOLhI2BbaFETICx4MlQitdqoUsCQ2vhKGjglNfU0SWmILaj43M5oEAOwAAAAAAAAAAAA==) no-repeat center left; }

lib/ex_doc/html_formatter/templates/css/style.css

@@ -75,6 +75,14 @@ ul.summary .summary_signature {
 }
 ul.summary .summary_signature:hover { background: #eeeeff; cursor: pointer; }
 
+table.summary tr:nth-child(odd) { background: #f0f0f0; }
+table.summary tr:nth-child(even) { background: #fafafa; }
+table.summary tr td { padding-top: 0.5em; padding-bottom: 0.5em; }
+
+td.summary_signature { padding-right: 0.5em; }
+td.summary_synopsis { padding-left: 0.5em; }
+td.summary_synopsis p { margin: 0em 0em; }
+
 /* File contents */
 #filecontents li > p, .docstring li > p { margin: 0px; }
 #filecontents ul, .docstring ul { padding-left: 20px; }

lib/ex_doc/html_formatter/templates/list_template.eex

@@ -23,6 +23,9 @@
  <a href="README.html">README</a>
  </h2>
  <% end %>
+ <h2 id="overview">
+ <a href="overview.html">Overview</a>
+ </h2>
  <div id="nav">
  <span class="<%= if(scope == :modules, do: "selected") %>"><a target="_self" href="modules_list.html">
  Modules

lib/ex_doc/html_formatter/templates/module_template.eex

@@ -50,23 +50,23 @@
 
  <%= unless Enum.empty?(functions) do %>
  <h2 id="functions_summary">Functions summary</h2>
- <ul class="summary">
+ <table class="summary">
  <%= lc node inlist functions, do: summary_template(node) %>
- </ul>
+ </table>
  <% end %>
 
  <%= unless Enum.empty?(macros) do %>
  <h2 id="macros_summary">Macros summary</h2>
- <ul class="summary">
+ <table class="summary">
  <%= lc node inlist macros, do: summary_template(node) %>
- </ul>
+ </table>
  <% end %>
 
  <%= unless Enum.empty?(callbacks) do %>
  <h2 id="callbacks_summary">Callbacks summary</h2>
- <ul class="summary">
+ <table class="summary">
  <%= lc node inlist callbacks, do: summary_template(node) %>
- </ul>
+ </table>
  <% end %>
 
  <%= unless Enum.empty?(types) do %>

lib/ex_doc/html_formatter/templates/overview_entry_template.eex

@@ -0,0 +1,6 @@
+<tr>
+ <td class="summary_signature"><a href="#<%=h node.id %>"><%=h node.id %></a></td>
+ <%= if node.moduledoc do %>
+ <td class="summary_synopsis"><%= to_html(synopsis(node.moduledoc)) %></td>
+ <% end %>
+</tr>

lib/ex_doc/html_formatter/templates/overview_template.eex

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Overview</title>
+ <meta charset="utf-8">
+ <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
+
+ <script type="text/javascript" charset="utf-8">
+ relpath = '';
+ if (relpath != '') relpath += '/';
+ </script>
+
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+ </head>
+
+ <body>
+ <script type="text/javascript" charset="utf-8">
+ if (window.top.frames.main) document.body.className = 'frames';
+ </script>
+
+ <h1><%= config.project %> v<%= config.version %></h1>
+
+ <div id="content">
+ <%= unless Enum.empty?(modules) do %>
+ <h2 id="modules_summary">Modules summary</h2>
+ <table class="summary">
+ <%= lc node inlist modules, do: overview_entry_template(node) %>
+ </table>
+ <% end %>
+
+ <%= unless Enum.empty?(records) do %>
+ <h2 id="records_summary">Records summary</h2>
+ <table class="summary">
+ <%= lc node inlist records, do: overview_entry_template(node) %>
+ </table>
+ <% end %>
+
+ <%= unless Enum.empty?(protocols) do %>
+ <h2 id="protocols_summary">Protocols summary</h2>
+ <table class="summary">
+ <%= lc node inlist protocols, do: overview_entry_template(node) %>
+ </table>
+ <% end %>
+ </div>
+ </body>
+</html>

lib/ex_doc/html_formatter/templates/summary_template.eex

@@ -1,5 +1,6 @@
-<li>
- <span class="summary_signature">
- <a href="#<%=h node.id %>"><%=h node.id %></a>
- </span>
-</li>
+<tr>
+ <td class="summary_signature"><a href="#<%=h node.id %>"><%=h signature(node) %></a></td>
+ <%= if node.doc do %>
+ <td class="summary_synopsis"><%= to_html(synopsis(node.doc)) %></td>
+ <% end %>
+</tr>

test/ex_doc/html_formatter/templates_test.exs

@@ -181,7 +181,7 @@ defmodule ExDoc.HTMLFormatter.TemplatesTest do
 
  test "module_page outputs summaries" do
  content = get_module_page([CompiledWithDocs])
- assert content =~ %r{<span class="summary_signature">\s*<a href="#example_1/0">}
+ assert content =~ %r{<td class="summary_signature">\s*<a href="#example_1/0">}
  end
 
  ## BEHAVIOURS