templates & rendering improvements, in part copied from elixir-lang#1992

Author: mayel

lib/ex_doc/formatter/markdown/templates.ex

@@ -43,63 +43,35 @@ defmodule ExDoc.Formatter.MARKDOWN.Templates do
   @spec synopsis(nil) :: nil
   def synopsis(doc) when is_binary(doc) do
     case :binary.split(doc, "\n\n") do
-      [left, _] -> String.trim_trailing(left, ": ")
+      [left, _] -> String.trim_trailing(left, ": ") <> "\n\n"
       [all] -> all
     end
   end
-  def synopsis(_), do: nil
-
-  @doc """
-  Add link headings for the given `content`.
 
-  IDs are prefixed with `prefix`.
-
-  We only link `h2` and `h3` headers. This is kept consistent in ExDoc.SearchData.
-  """
-  @heading_regex ~r/<(h[23]).*?>(.*?)<\/\1>/m
-  @spec link_headings(String.t() | nil, String.t()) :: String.t() | nil
-  def link_headings(content, prefix \\ "")
-  def link_headings(nil, _), do: nil
+  def synopsis(_), do: nil
 
-  def link_headings(content, prefix) do
+  @heading_regex ~r/^(\#{1,6})\s+(.*)/m
+  defp rewrite_headings(content) when is_binary(content) do
     @heading_regex
     |> Regex.scan(content)
-    |> Enum.reduce({content, %{}}, fn [match, tag, title], {content, occurrences} ->
-      possible_id = text_to_id(title)
-      id_occurred = Map.get(occurrences, possible_id, 0)
-
-      anchor_id = if id_occurred >= 1, do: "#{possible_id}-#{id_occurred}", else: possible_id
-      replacement = link_heading(match, tag, title, anchor_id, prefix)
-      linked_content = String.replace(content, match, replacement, global: false)
-      incremented_occs = Map.put(occurrences, possible_id, id_occurred + 1)
-      {linked_content, incremented_occs}
+    |> Enum.reduce(content, fn [match, level, title], content ->
+      replacement = rewrite_heading(level, title)
+      String.replace(content, match, replacement, global: false)
     end)
-    |> elem(0)
   end
 
-  defp link_heading(match, _tag, _title, "", _prefix), do: match
+  defp rewrite_headings(_), do: nil
 
-  defp link_heading(_match, _tag, title, id, prefix) do
-    # The Markdown syntax that we support for the admonition text
-    # blocks is something like this:
-    #
-    #     > ### Never open this door! {: .warning}
-    #     >
-    #     > ...
-    #
+  defp rewrite_heading("#", title), do: do_rewrite_heading("#####", title)
+  defp rewrite_heading(_, title), do: do_rewrite_heading("######", title)
 
+  defp do_rewrite_heading(level, title) do
     """
-    ## [#{title}](##{prefix}#{id})
+    #{level} #{title}
     """
   end
 
-  def link_moduledoc_headings(content) do
-    link_headings(content, "module-")
-  end
-
-  def link_detail_headings(content, prefix) do
-    link_headings(content, prefix <> "-")
-  end
+  defp enc(binary), do: URI.encode(binary) |> String.replace("/", "-")
 
   @doc """
   Creates a chapter which contains all the details about an individual module.

lib/ex_doc/formatter/markdown/templates/detail_template.eex

@@ -1,21 +1,15 @@
-# <%=h node.signature %>
-
-<%= if node.source_url do %>
-[View Source](<%= node.source_url %>)
-<% end %>
-
-<%= for annotation <- node.annotations do %>
-> (<%= annotation %>)
-<% end %>
+<a id="<%= enc node.id %>"></a>
+#### `<%=h node.signature %>` <%= if node.source_url do %>[🔗](<%= node.source_url %>)<% end %> <%= for annotation <- node.annotations do %>(<%= annotation %>) <% end %>
 
 <%= if deprecated = node.deprecated do %>
 > This <%= node.type %> is deprecated. <%= h(deprecated) %>.
 <% end %>
 
 <%= if node.specs != [] do %>
-<%= for spec <- node.specs do %>
-> <%= H.format_spec_attribute(module, node) %>: <%= spec %>
+<%= for spec <- node.specs do %> 
+> <%= H.format_spec_attribute(module, node) %> <%= spec %>
 <% end %>
 <% end %>
 
-<%= link_detail_headings(node_doc(node), H.enc(node.id)) %>
+<%= rewrite_headings(node_doc(node)) %>
+

lib/ex_doc/formatter/markdown/templates/module_template.eex

@@ -1,20 +1,36 @@
-# <%= module.title %> <%= module_type(module) %>
+# <%= module.title %> <%= module_type(module) %> (<%= config.project %> v<%= config.version %>)
+
+<%= for annotation <- module.annotations do %>*(<%= annotation %>)* <% end %>
 
 <%= if deprecated = module.deprecated do %>
 > This <%= module.type %> is deprecated. <%=h deprecated %>.
 <% end %>
 
 <%= if doc = node_doc(module) do %>
-<%= H.link_moduledoc_headings(doc) %>
+<%= doc %>
 <% end %>
 
 <%= if summary != [] do %>
-## Summary
+## Table of Contents
 <%= for {name, nodes} <- summary, do: summary_template(name, nodes) %>
 <% end %>
 
+## Contents
+
 <%= for {name, nodes} <- summary, _key = text_to_id(name) do %>
-## <%=h to_string(name) %>
-<%= for node <- nodes, do: detail_template(node, module) %>
+
+### <%=h to_string(name) %>
+
+<%= for node <- nodes do %>
+<%= detail_template(node, module) %>
+<% end %>
+
 <% end %>
+
+---
+
+<%= if module.source_url do %>
+[<%= String.capitalize(to_string(module.type)) %> Source Code](<%= module.source_url %>)
+<% end %>
+
 <%= before_closing_body_tag(config, :markdown) %>

lib/ex_doc/formatter/markdown/templates/nav_item_template.eex

@@ -1,6 +1,6 @@
 <%= unless Enum.empty?(nodes) do %>
 - <%= name %>
 <%= for node <- nodes do %>
-1. [<%=h node.title %>](<%= URI.encode node.id %>.md)
+  - [<%=h node.title %>](<%= URI.encode node.id %>.md)
 <% end %>
 <% end %>

lib/ex_doc/formatter/markdown/templates/nav_template.eex

@@ -1,4 +1,4 @@
-# Table of contents
+# <%= config.project %> v<%= config.version %> - Documentation - Table of contents
 
 <%= nav_grouped_item_template config.extras  %>
 <%= unless Enum.empty?(nodes.modules) do %>

lib/ex_doc/formatter/markdown/templates/summary_template.eex

@@ -1,7 +1,8 @@
-## <%= name %>
+### <%= name %>
+
 <%= for node <- nodes do %>
 
-### <%=h node.signature %>
+#### [`<%=h node.signature %>`](#<%= enc node.id %>)
 
 <%= if deprecated = node.deprecated do %>
 > <%= h(deprecated) %>
@@ -10,4 +11,5 @@
 <%= if doc = node_doc(node) do %>
 <%= synopsis(doc) %>
 <% end %>
+
 <% end %>

test/ex_doc/formatter/markdown/templates_test.exs

@@ -56,20 +56,20 @@ defmodule ExDoc.Formatter.MARKDOWN.TemplatesTest do
 
       assert content =~ ~r{#\s*CompiledWithDocs\s*}
 
-      assert content =~ ~s{# Summary</h1>}
+      assert content =~ ~s{## Table of Contents}
 
       assert content =~
-               ~r{## .*Example.*}ms
+               ~r{\n## .*Example.*}ms
 
       assert content =~
-               ~r{### .*Example H3 heading.*}ms
+               ~r{\n### .*Example H3 heading.*}ms
 
       assert content =~
                ~r{moduledoc.*Example.*CompiledWithDocs\.example.*}ms
 
       assert content =~ ~r{Some example}ms
       assert content =~ ~r{example_without_docs().*}ms
-      assert content =~ ~r{example_1().*> \(macro\)}ms
+      assert content =~ ~r{example_1().* \(macro\)}ms
 
       assert content =~ ~s{example(foo, bar \\\\ Baz)}
     end

test/ex_doc/formatter/markdown_test.exs

@@ -72,6 +72,6 @@ defmodule ExDoc.Formatter.MARKDOWNTest do
              ~r{\n`TypesAndSpecs.Sub`\n}
 
     content = File.read!(tmp_dir <> "/markdown/index.md")
-    assert content =~ "# Table of contents\n\n  - [README](readme.md)"
+    assert content =~ "Table of contents\n\n  - [README](readme.md)"
   end
 end