Add Hex package config and display "Find on Hex" footer links (#1385)

assets/less/content/footer.less

@@ -20,6 +20,10 @@
     .linkUnderlines(@mediumGray)
   }
 
+  .footer-hex-package {
+    margin-right: 4px;
+  }
+
   a {
     color: @mediumGray;
     .linkUnderlines(@mediumGray)

lib/ex_doc/cli.ex

@@ -24,6 +24,7 @@ defmodule ExDoc.CLI do
         switches: [
           language: :string,
           paths: :keep,
+          package: :string,
           proglang: :string,
           source_ref: :string,
           version: :boolean
@@ -156,6 +157,7 @@ defmodule ExDoc.CLI do
       -l, --logo          Path to the image logo of the project (only PNG or JPEG accepted)
                           The image size will be 64x64 and copied to the assets directory
       -m, --main          The entry-point page in docs, default: "api-reference"
+          --package       Hex package name
           --source-ref    Branch/commit/tag used for source link inference, default: "master"
       -r, --source-root   Path to the source code root, used for generating links, default: "."
       -u, --source-url    URL to the source code

lib/ex_doc/config.ex

@@ -43,7 +43,8 @@ defmodule ExDoc.Config do
             title: nil,
             version: nil,
             authors: nil,
-            skip_undefined_reference_warnings_on: []
+            skip_undefined_reference_warnings_on: [],
+            package: nil
 
   @type t :: %__MODULE__{
           apps: [atom()],
@@ -78,6 +79,7 @@ defmodule ExDoc.Config do
           title: nil | String.t(),
           version: nil | String.t(),
           authors: nil | [String.t()],
-          skip_undefined_reference_warnings_on: [String.t()]
+          skip_undefined_reference_warnings_on: [String.t()],
+          package: :atom | nil
         }
 end

lib/ex_doc/formatter/html.ex

@@ -205,8 +205,8 @@ defmodule ExDoc.Formatter.HTML do
   defp generate_extras(nodes_map, extras, config) do
     extras
     |> with_prev_next()
-    |> Enum.map(fn {%{id: id, title: title, content: content}, prev, next} ->
-      filename = "#{id}.html"
+    |> Enum.map(fn {node, prev, next} ->
+      filename = "#{node.id}.html"
       output = "#{config.output}/#{filename}"
       config = set_canonical_url(config, filename)
 
@@ -215,7 +215,7 @@ defmodule ExDoc.Formatter.HTML do
         next: next && %{path: "#{next.id}.html", title: next.title}
       }
 
-      html = Templates.extra_template(config, title, nodes_map, content, refs)
+      html = Templates.extra_template(config, node, nodes_map, refs)
 
       if File.regular?(output) do
         IO.puts(:stderr, "warning: file #{Path.relative_to_cwd(output)} already exists")
@@ -338,7 +338,7 @@ defmodule ExDoc.Formatter.HTML do
     group = GroupMatcher.match_extra(groups, input)
     title = title || extract_title(html_content) || filename_to_title(input)
 
-    %{id: id, title: title, group: group, content: html_content}
+    %{id: id, title: title, group: group, content: html_content, source_path: input}
   end
 
   defp extension_name(input) do

lib/ex_doc/formatter/html/templates.ex

@@ -267,13 +267,13 @@ defmodule ExDoc.Formatter.HTML.Templates do
 
   templates = [
     detail_template: [:node, :_module],
-    footer_template: [:config],
+    footer_template: [:config, :node],
     head_template: [:config, :page],
     module_template: [:config, :module, :summary, :nodes_map],
     not_found_template: [:config, :nodes_map],
     api_reference_entry_template: [:module_node],
     api_reference_template: [:config, :nodes_map],
-    extra_template: [:config, :title, :nodes_map, :content, :refs],
+    extra_template: [:config, :node, :nodes_map, :refs],
     search_template: [:config, :nodes_map],
     sidebar_template: [:config, :nodes_map],
     summary_template: [:name, :nodes],

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

@@ -1,6 +1,6 @@
-<%= head_template(config, %{title: title, type: :extra}) %>
+<%= head_template(config, %{title: node.title, type: :extra}) %>
 <%= sidebar_template(config, nodes_map) %>
 
-<%= link_headings(content) %>
+<%= link_headings(node.content) %>
 <%= bottom_actions_template(refs) %>
-<%= footer_template(config) %>
+<%= footer_template(config, node) %>

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

@@ -1,4 +1,16 @@
       <footer class="footer">
+        <%= if config.package do %>
+
+        <p>
+          Find it on Hex:
+          <a href="https://hex.pm/packages/<%= config.package %>/<%= config.version %>" class="line footer-hex-package">Package</a>
+          <a href="https://preview.hex.pm/preview/<%= config.package %>/<%= config.version %>" class="line">Preview</a>
+
+          <%= source_path = node && Map.get(node, :source_path); if source_path do %>
+            <a href="https://preview.hex.pm/preview/<%= config.package %>/<%= config.version %>/show/<%= source_path %>">(current file)</a>
+          <% end %>
+        </p>
+        <% end %>
         <p>
           <span class="line">
             Built using

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

@@ -50,4 +50,4 @@
           </div>
         </section>
       <% end %>
-    <%= footer_template(config) %>
+    <%= footer_template(config, module) %>

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

@@ -10,4 +10,4 @@ may want to try searching this site using the sidebar
 <% end %>
 to find what you were looking for.</p>
 
-<%= footer_template(config) %>
+<%= footer_template(config, nil) %>

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

@@ -5,4 +5,4 @@
   <div class="loading"><div></div><div></div><div></div><div></div></div>
 </div>
 <script src="<%= asset_rev config.output, "dist/search_items*.js" %>"></script>
-<%= footer_template(config) %>
+<%= footer_template(config, nil) %>

lib/mix/tasks/docs.ex

@@ -341,6 +341,7 @@ defmodule Mix.Tasks.Docs do
       |> normalize_apps(config)
       |> normalize_main()
       |> normalize_deps()
+      |> put_package(config)
 
     Mix.shell().info("Generating docs...")
 
@@ -453,4 +454,12 @@ defmodule Mix.Tasks.Docs do
       {key, "https://hexdocs.pm/#{key}/#{vsn}/"}
     end
   end
+
+  defp put_package(options, config) do
+    if package = config[:package] do
+      Keyword.put(options, :package, package[:name] || config[:app])
+    else
+      options
+    end
+  end
 end