Merge pull request #3 from cryic/sidebar-title-updates

Add title tag with properly formatted mfa to sidebar

Author: matlc

assets/js/templates/sidebar-items.handlebars

@@ -24,38 +24,38 @@
 
       <ul>
         <li>
-          <a href="{{node.id}}.html#content">Top</a>
+          <a href="{{node.id}}.html#content" title="{{node.title}}">Top</a>
         </li>
 
         {{#isArray node.headers}}
           {{#each node.headers}}
             <li>
-              <a href="{{node.id}}.html#{{{anchor}}}">{{id}}</a>
+              <a href="{{node.id}}.html#{{{anchor}}}" title="{{node.title}} — {{id}}">{{id}}</a>
             </li>
           {{/each}}
         {{else}}
           {{#showSummary node}}
             <li>
-              <a href="{{node.id}}.html#summary">Summary</a>
+              <a href="{{node.id}}.html#summary" title="{{node.title}} Summary">Summary</a>
             </li>
           {{/showSummary}}
           {{#each node.nodeGroups as |group|}}
             <li class="docs">
-              <a href="{{node.id}}.html#{{group.key}}" class="expand">
+              <a href="{{node.id}}.html#{{group.key}}" class="expand" title="{{node.title}} {{group.name}}">
                 {{group.name}}
                 <span class="icon-goto" title="Go to {{group.name}}"></span>
               </a>
               <ul class="{{group.key}}-list deflist">
                 {{#each group.nodes}}
                   <li>
-                    <a href="{{node.id}}.html#{{anchor}}">{{id}}</a>
+                    <a href="{{node.id}}.html#{{anchor}}" title="{{link_title}}">{{id}}</a>
                   </li>
                 {{/each}}
               </ul>
             </li>
           {{/each}}
         {{/isArray}}
-        </ul>
+      </ul>
     </li>
   {{/each}}
 </ul>

formatters/epub/dist/epub-7b73f2ed8c1683aa4f8b.css renamed to formatters/epub/dist/epub-e17fcd3fcf52d88e08d0.css

@@ -12,7 +12,7 @@
     <%= if Enum.any?(summary, fn {_, v} -> v != [] end) do %>
       <section id="summary" class="details-list">
         <h1 class="section-heading">
-          <a class="hover-link" href="#summary">
+          <a class="hover-link" href="#summary" title="Link to module-summary">
             <span class="icon-link" aria-hidden="true"></span>
             <span class="sr-only">Anchor for this section</span>
           </a>
@@ -25,7 +25,7 @@
     <%= for {name, nodes} <- summary, nodes != [], key = HTML.text_to_id(name) do %>
       <section id="<%= key %>" class="details-list">
         <h1 class="section-heading">
-          <a class="hover-link" href="#<%= key %>">
+          <a class="hover-link" href="#<%= key %>" title="Link to <%= key %>">
             <span class="icon-link" aria-hidden="true"></span>
             <span class="sr-only">Anchor for this section</span>
           </a>

formatters/epub/dist/epub-7b73f2ed8c1683aa4f8b.js renamed to formatters/epub/dist/epub-e17fcd3fcf52d88e08d0.js

@@ -10,7 +10,9 @@ defmodule ExDoc.Formatter.HTML.Autolink do
   @elixir_docs "https://hexdocs.pm/"
   @erlang_docs "http://www.erlang.org/doc/man/"
   @basic_types_page "typespecs.html#basic-types"
+  @basic_types_link_title "Basic types — Typespecs"
   @built_in_types_page "typespecs.html#built-in-types"
+  @built_in_types_link_title "Built-in types — Typespecs"
 
   @basic_types [
     any: 0,
@@ -188,6 +190,7 @@ defmodule ExDoc.Formatter.HTML.Autolink do
 
   defp all_typespecs(module, compiled) do
     %{aliases: aliases, lib_dirs: lib_dirs} = compiled
+    module_name = module.title
 
     locals =
       Enum.map(module.typespecs, fn
@@ -196,14 +199,15 @@ defmodule ExDoc.Formatter.HTML.Autolink do
 
     typespecs =
       for typespec <- module.typespecs do
-        %{typespec | spec: typespec(typespec.spec, locals, aliases, lib_dirs)}
+        %{typespec | spec: typespec(typespec.spec, locals, module_name, aliases, lib_dirs)}
       end
 
     docs =
       for module_node <- module.docs do
         %{
           module_node
-          | specs: Enum.map(module_node.specs, &typespec(&1, locals, aliases, lib_dirs))
+          | specs:
+              Enum.map(module_node.specs, &typespec(&1, locals, module_name, aliases, lib_dirs))
         }
       end
 
@@ -216,15 +220,15 @@ defmodule ExDoc.Formatter.HTML.Autolink do
   It converts the given `ast` to string while linking
   the locals given by `typespecs` as HTML.
   """
-  def typespec(ast, typespecs, aliases \\ [], lib_dirs \\ default_lib_dirs()) do
+  def typespec(ast, typespecs, module_name, aliases \\ [], lib_dirs \\ default_lib_dirs()) do
     {formatted, placeholders} =
-      format_and_extract_typespec_placeholders(ast, typespecs, aliases, lib_dirs)
+      format_and_extract_typespec_placeholders(ast, typespecs, module_name, aliases, lib_dirs)
 
     replace_placeholders(formatted, placeholders)
   end
 
   @doc false
-  def format_and_extract_typespec_placeholders(ast, typespecs, aliases, lib_dirs) do
+  def format_and_extract_typespec_placeholders(ast, typespecs, module_name, aliases, lib_dirs) do
     ref = make_ref()
     elixir_docs = get_elixir_docs(aliases, lib_dirs)
 
@@ -244,16 +248,17 @@ defmodule ExDoc.Formatter.HTML.Autolink do
           cond do
             {name, arity} in @basic_types ->
               url = elixir_docs <> @basic_types_page
-              put_placeholder(form, url, placeholders)
+              put_placeholder(form, url, @basic_types_link_title, placeholders)
 
             {name, arity} in @built_in_types ->
               url = elixir_docs <> @built_in_types_page
-              put_placeholder(form, url, placeholders)
+              put_placeholder(form, url, @built_in_types_link_title, placeholders)
 
             {name, arity} in typespecs ->
               n = enc_h("#{name}")
               url = "#t:#{n}/#{arity}"
-              put_placeholder(form, url, placeholders)
+              title = "t:#{module_name}.#{n}/#{arity}"
+              put_placeholder(form, url, title, placeholders)
 
             true ->
               {form, placeholders}
@@ -265,7 +270,8 @@ defmodule ExDoc.Formatter.HTML.Autolink do
 
           if source = get_source(alias, aliases, lib_dirs) do
             url = type_remote_url(source, alias, name, args)
-            put_placeholder(form, url, placeholders)
+            title = type_remote_link_title(source, alias, name, args)
+            put_placeholder(form, url, title, placeholders)
           else
             {form, placeholders}
           end
@@ -288,14 +294,22 @@ defmodule ExDoc.Formatter.HTML.Autolink do
     "#{source}#{enc_h(inspect(alias))}.html#t:#{name}/#{length(args)}"
   end
 
-  defp typespec_string_to_link(string, url) do
+  defp type_remote_link_title(@erlang_docs, module, name, _args) do
+    "#{module}:#{name}"
+  end
+
+  defp type_remote_link_title(_source, alias, name, args) do
+    "t:#{inspect(alias)}.#{name}/#{length(args)}"
+  end
+
+  defp typespec_string_to_link(string, url, title) do
     {string_to_link, _string_with_parens} = split_string_to_link(string)
-    ~s[<a href="#{url}">#{h(string_to_link)}</a>]
+    ~s[<a href="#{url}" title="#{title}">#{h(string_to_link)}</a>]
   end
 
-  defp put_placeholder(form, url, placeholders) do
+  defp put_placeholder(form, url, title, placeholders) do
     string = Macro.to_string(form)
-    link = typespec_string_to_link(string, url)
+    link = typespec_string_to_link(string, url, title)
 
     case Enum.find(placeholders, fn {_key, value} -> value == link end) do
       {placeholder, _} ->

formatters/html/dist/html-17f11fce3c17ca7c2e4e.css renamed to formatters/html/dist/html-ee6ad1641e689858a6e0.css

@@ -71,6 +71,14 @@ defmodule ExDoc.Formatter.HTML.Templates do
     end
   end
 
+  @doc """
+  Generate a link title
+  """
+  def link_title(module, node) do
+    mfa_without_prefix = "#{module.id}.#{node.id}"
+    link_id(mfa_without_prefix, node.type)
+  end
+
   @doc """
   Returns the HTML formatted title for the module page.
   """
@@ -157,11 +165,20 @@ defmodule ExDoc.Formatter.HTML.Templates do
     headers =
       content
       |> extract_headers
-      |> Enum.map_join(",", fn {header, anchor} -> sidebar_items_object(header, anchor) end)
+      |> Enum.map_join(",", fn {header, anchor} ->
+        sidebar_items_object(header, anchor, hyphenize(id, title))
+      end)
 
     ~s/{"id":"#{id}","title":"#{title}","group":"#{group}","headers":[#{headers}]}/
   end
 
+  defp hyphenize(id, title) do
+    [id, title]
+    |> Enum.filter(&(&1 != ""))
+    |> Enum.filter(&(&1 != nil))
+    |> Enum.join(" — ")
+  end
+
   @h2_regex ~r/<h2.*?>(.*?)<\/h2>/m
   defp extract_headers(content) do
     @h2_regex
@@ -173,26 +190,30 @@ defmodule ExDoc.Formatter.HTML.Templates do
   end
 
   defp sidebar_items_node(module_node) do
+    sidebar_items_by_group_with_module = fn group ->
+      sidebar_items_by_group(module_node, group)
+    end
+
     items =
       module_node
       |> module_summary()
       |> Enum.reject(fn {_type, nodes_map} -> nodes_map == [] end)
-      |> Enum.map_join(",", &sidebar_items_by_group/1)
+      |> Enum.map_join(",", fn group -> sidebar_items_by_group_with_module.(group) end)
 
     sidebar_items_json_string(module_node, items)
   end
 
-  defp sidebar_items_by_group({group, docs}) do
+  defp sidebar_items_by_group(module_node, {group, docs}) do
     objects =
       Enum.map_join(docs, ",", fn doc ->
-        sidebar_items_object(doc.id, link_id(doc))
+        sidebar_items_object(doc.id, link_id(doc), link_title(module_node, doc))
       end)
 
     ~s/{"key":"#{HTML.text_to_id(group)}","name":"#{group}","nodes":[#{objects}]}/
   end
 
-  defp sidebar_items_object(id, anchor) do
-    ~s/{"id":"#{id}","anchor":"#{URI.encode(anchor)}"}/
+  defp sidebar_items_object(id, anchor, title) do
+    ~s/{"id":"#{id}","anchor":"#{URI.encode(anchor)}","link_title":"#{title}"}/
   end
 
   defp sidebar_items_json_string(module_node, items) do
@@ -269,7 +290,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
   defp link_heading(_match, tag, title, id, prefix) do
     """
     <#{tag} id="#{prefix}#{id}" class="section-heading">
-      <a href="##{prefix}#{id}" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+      <a href="##{prefix}#{id}" class="hover-link" title="Link to #{prefix}#{id}"><span class="icon-link" aria-hidden="true"></span></a>
       #{title}
     </#{tag}>
     """

formatters/html/dist/html-17f11fce3c17ca7c2e4e.js renamed to formatters/html/dist/html-ee6ad1641e689858a6e0.js

@@ -6,9 +6,9 @@
     <span id="<%=enc_h link_id(default, node.type) %>"></span>
   <% end %>
   <div class="detail-header">
-    <a href="#<%=enc_h link_id(node) %>" class="detail-link" title="Link to <%= "#{module.title}.#{link_id(node)}" %>">
+    <a href="#<%=enc_h link_id(node) %>" class="detail-link" title="Link to <%= link_title(module, node) %>">
       <span class="icon-link" aria-hidden="true"></span>
-      <span class="sr-only">Link to <%= "#{module.title}.#{link_id(node)}" %></span>
+      <span class="sr-only">Link to <%= link_title(module, node) %></span>
     </a>
     <h1 class="signature"><%=h node.signature %></span>
     <%= if node.source_url do %>

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

@@ -27,7 +27,7 @@
       <%= if Enum.any?(summary, fn {_, v} -> v != [] end) do %>
         <section id="summary" class="details-list">
           <h1 class="section-heading">
-            <a class="hover-link" href="#summary">
+            <a class="hover-link" href="#summary" title="Link to <%= module.title %> — Summary">
               <span class="icon-link" aria-hidden="true"></span>
               <span class="sr-only">Link to this section</span>
             </a>
@@ -40,7 +40,7 @@
       <%= for {name, nodes} <- summary, nodes != [], key = HTML.text_to_id(name) do %>
         <section id="<%= key %>" class="details-list">
           <h1 class="section-heading">
-            <a class="hover-link" href="#<%= key %>">
+            <a class="hover-link" href="#<%= key %>" title="Link to <%= module.title %> — <%= name %>">
               <span class="icon-link" aria-hidden="true"></span>
               <span class="sr-only">Link to this section</span>
             </a>