Compute synopsis using AST

Closes #2108.
Closes #2110.

Author: josevalim

lib/ex_doc/doc_ast.ex

@@ -110,6 +110,37 @@ defmodule ExDoc.DocAST do
   def extract_title([{:h1, _attrs, inner, _meta} | ast]), do: {:ok, inner, ast}
   def extract_title(_ast), do: :error
 
+  @doc """
+  Compute a synopsis from a document by looking at its first paragraph.
+  """
+  def synopsis({:p, _attrs, [_ | _] = inner, meta}) do
+    inner =
+      case Enum.split(inner, -1) do
+        {pre, [post]} when is_binary(post) ->
+          pre ++ [String.trim_trailing(post, ":")]
+
+        _ ->
+          inner
+      end
+
+    ExDoc.DocAST.to_string({:p, [], remove_ids(inner), meta})
+  end
+
+  def synopsis([head | _]), do: synopsis(head)
+  def synopsis(_other), do: ""
+
+  @doc """
+  Remove ids from elements.
+  """
+  def remove_ids({tag, attrs, inner, meta}),
+    do: {tag, Keyword.delete(attrs, :href), remove_ids(inner), meta}
+
+  def remove_ids(list) when is_list(list),
+    do: Enum.map(list, &remove_ids/1)
+
+  def remove_ids(other),
+    do: other
+
   @doc """
   Returns text content from the given AST.
   """

lib/ex_doc/formatter/html/templates.ex

@@ -41,30 +41,6 @@ defmodule ExDoc.Formatter.HTML.Templates do
   def module_type(%{type: :module}), do: ""
   def module_type(%{type: type}), do: "<small>#{type}</small>"
 
-  @doc """
-  Gets the first paragraph of the documentation of a node. It strips
-  surrounding white-spaces and trailing `:`.
-
-  If `doc` is `nil`, it returns `nil`.
-  """
-  @spec synopsis(String.t()) :: String.t()
-  @spec synopsis(nil) :: nil
-  def synopsis(nil), do: nil
-
-  def synopsis(doc) when is_binary(doc) do
-    doc =
-      case :binary.split(doc, "</p>") do
-        [left, _] -> String.trim_trailing(left, ":") <> "</p>"
-        [all] -> all
-      end
-
-    # Remove any anchors found in synopsis.
-    # Old Erlang docs placed anchors at the top of the documentation
-    # for links. Ideally they would have been removed but meanwhile
-    # it is simpler to guarantee they won't be duplicated in docs.
-    Regex.replace(~r|(<[^>]*) id="[^"]*"([^>]*>)|, doc, ~S"\1\2", [])
-  end
-
   defp enc(binary), do: URI.encode(binary)
 
   @doc """

lib/ex_doc/formatter/html/templates/api_reference_entry_template.eex

@@ -5,7 +5,7 @@
       <span class="deprecated" title="<%= h(deprecated) %>">deprecated</span>
     <% end %>
   </div>
-  <%= if doc = module_node.rendered_doc do %>
-    <div class="summary-synopsis"><%= synopsis(doc) %></div>
+  <%= if doc = module_node.doc do %>
+    <div class="summary-synopsis"><%= ExDoc.DocAST.synopsis(doc) %></div>
   <% end %>
 </div>

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

@@ -10,8 +10,8 @@
           <span class="deprecated" title="<%= h(deprecated) %>">deprecated</span>
         <% end %>
       </div>
-      <%= if doc = node.rendered_doc do %>
-        <div class="summary-synopsis"><%= synopsis(doc) %></div>
+      <%= if doc = node.doc do %>
+        <div class="summary-synopsis"><%= ExDoc.DocAST.synopsis(doc) %></div>
       <% end %>
     </div>
   <% end %>

test/ex_doc/doc_ast_test.exs

@@ -104,7 +104,7 @@ defmodule ExDoc.DocASTTest do
 
     test "void elements" do
       markdown = """
-      foo  
+      foo\s\s
       bar
       """
 
@@ -114,6 +114,42 @@ defmodule ExDoc.DocASTTest do
     end
   end
 
+  describe "synopsis" do
+    test "functionality" do
+      assert synopsis("") == ""
+      assert synopsis("<p>.</p>") == "<p>.</p>"
+      assert synopsis("<p>::</p>") == "<p></p>"
+      assert synopsis("<p>Description:</p>") == "<p>Description</p>"
+      assert synopsis("<p>abcd</p>") == "<p>abcd</p>"
+    end
+
+    test "should not end have trailing periods or semicolons" do
+      doc1 = """
+      Summaries should not be displayed with trailing semicolons :
+
+      ## Example
+      """
+
+      doc2 = """
+      Example function: Summary should display trailing period :.
+
+      ## Example:
+      """
+
+      assert synopsis(doc1) ==
+               "<p>Summaries should not be displayed with trailing semicolons </p>"
+
+      assert synopsis(doc2) ==
+               "<p>Example function: Summary should display trailing period :.</p>"
+    end
+
+    defp synopsis(markdown) do
+      markdown
+      |> ExDoc.DocAST.parse!("text/markdown")
+      |> ExDoc.DocAST.synopsis()
+    end
+  end
+
   describe "highlight" do
     test "with default class" do
       # Empty class

test/ex_doc/formatter/html/templates_test.exs

@@ -161,43 +161,6 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
     end
   end
 
-  describe "synopsis" do
-    test "functionality" do
-      assert Templates.synopsis(nil) == nil
-      assert Templates.synopsis("") == ""
-      assert Templates.synopsis("<p>.</p>") == "<p>.</p>"
-      assert Templates.synopsis("<p>::</p>") == "<p></p>"
-      assert Templates.synopsis("<p>Description:</p>") == "<p>Description</p>"
-      assert Templates.synopsis("<p>abcd</p>") == "<p>abcd</p>"
-    end
-
-    test "should not end have trailing periods or semicolons" do
-      doc1 = """
-      Summaries should not be displayed with trailing semicolons :
-
-      ## Example
-      """
-
-      doc2 = """
-      Example function: Summary should display trailing period :.
-
-      ## Example:
-      """
-
-      assert Templates.synopsis(to_html(doc1)) ==
-               "<p>Summaries should not be displayed with trailing semicolons </p>"
-
-      assert Templates.synopsis(to_html(doc2)) ==
-               "<p>Example function: Summary should display trailing period :.</p>"
-    end
-  end
-
-  defp to_html(markdown) do
-    markdown
-    |> ExDoc.DocAST.parse!("text/markdown")
-    |> ExDoc.DocAST.to_string()
-  end
-
   describe "sidebar" do
     test "text links to homepage_url when set", context do
       content = Templates.sidebar_template(doc_config(context), :extra)