Detect asset names and contents at compile-time whenever possible

elixir-lang · Dec 31, 2024 · e622438 · e622438
1 parent 62b600c
commit e622438
Show file tree

Hide file tree

Showing 11 changed files with 59 additions and 37 deletions.
diff --git a/assets/build/build.js b/assets/build/build.js
@@ -26,7 +26,7 @@ const formatters = [
     formatter: 'html',
     outdir: path.resolve('../formatters/html/dist'),
     entryPoints: [
-      'js/entry/html_inline.js',
+      'js/entry/inline_html.js',
       'js/entry/html.js',
       'css/entry/html-elixir.css',
       'css/entry/html-erlang.css'

diff --git a/assets/js/constants.js b/assets/js/constants.js
@@ -1,3 +1,3 @@
-// Constants separated to allow importing into html_inline.js without
+// Constants separated to allow importing into inline_html.js without
 // bringing in other code.
 export const SETTINGS_KEY = 'ex_doc:settings'
diff --git a/assets/js/entry/html_inline.js → assets/js/entry/inline_html.js b/assets/js/entry/html_inline.js → assets/js/entry/inline_html.js
diff --git a/formatters/html/dist/html_inline-ODE4BZGP.js → formatters/html/dist/inline_html-ZIAMPHXB.js b/formatters/html/dist/html_inline-ODE4BZGP.js → formatters/html/dist/inline_html-ZIAMPHXB.js
diff --git a/lib/ex_doc/formatter/epub/assets.ex b/lib/ex_doc/formatter/epub/assets.ex
@@ -11,11 +11,21 @@ defmodule ExDoc.Formatter.EPUB.Assets do
     end)
   end
 
-  def dist(proglang), do: dist_js() ++ dist_css(proglang)
-
   defp dist_js(), do: embed_pattern("dist/*.js")
   defp dist_css(:elixir), do: embed_pattern("dist/epub-elixir-*.css")
   defp dist_css(:erlang), do: embed_pattern("dist/epub-erlang-*.css")
 
+  ## Assets
+
+  def dist(proglang), do: dist_js() ++ dist_css(proglang)
   def metainfo, do: embed_pattern("metainfo/*")
+
+  ## Filenames
+
+  def js_filename(), do: dist_js() |> extract_filename!()
+  def css_filename(language), do: dist_css(language) |> extract_filename!()
+
+  ## Helpers
+
+  defp extract_filename!([{location, _}]), do: location
 end
diff --git a/lib/ex_doc/formatter/epub/templates.ex b/lib/ex_doc/formatter/epub/templates.ex
@@ -7,6 +7,7 @@ defmodule ExDoc.Formatter.EPUB.Templates do
     only: [before_closing_body_tag: 2, before_closing_head_tag: 2, h: 1, text_to_id: 1]
 
   alias ExDoc.Formatter.HTML.Templates, as: H
+  alias ExDoc.Formatter.EPUB.Assets
 
   @doc """
   Generate content from the module template for a given `node`

diff --git a/lib/ex_doc/formatter/epub/templates/head_template.eex b/lib/ex_doc/formatter/epub/templates/head_template.eex
@@ -5,9 +5,8 @@
     <meta charset="utf-8" />
     <title><%= title %> - <%= config.project %> v<%= config.version %></title>
     <meta name="generator" content="ExDoc v<%= ExDoc.version() %>" />
-    <link type="text/css" rel="stylesheet"
-      href="<%= H.asset_rev "#{config.output}/OEBPS", "dist/epub-#{config.proglang}-*.css" %>" />
-    <script src="<%= H.asset_rev "#{config.output}/OEBPS", "dist/epub-*.js" %>"></script>
+    <link type="text/css" rel="stylesheet" href="dist/<%= Assets.css_filename(config.proglang) %>" />
+    <script src="dist/<%= Assets.js_filename() %>"></script>
     <%= before_closing_head_tag(config, :epub) %>
   </head>
   <body class="content-inner">
diff --git a/lib/ex_doc/formatter/html/assets.ex b/lib/ex_doc/formatter/html/assets.ex
@@ -8,12 +8,45 @@ defmodule ExDoc.Formatter.HTML.Assets do
     |> Enum.map(&{Path.basename(&1), File.read!(&1)})
   end
 
-  def dist(proglang), do: dist_js() ++ dist_css(proglang) ++ dist_license()
-
-  defp dist_js(), do: embed_pattern("dist/*.js")
+  defp dist_js(), do: embed_pattern("dist/html-*.js")
+  defp dist_inline_js(), do: embed_pattern("dist/inline_html-*.js")
   defp dist_css(:elixir), do: embed_pattern("dist/html-elixir-*.css")
   defp dist_css(:erlang), do: embed_pattern("dist/html-erlang-*.css")
   defp dist_license(), do: embed_pattern("dist/*.LICENSE.txt")
 
+  ## Assets
+
+  def dist(proglang), do: dist_js() ++ dist_css(proglang) ++ dist_license()
   def fonts, do: embed_pattern("dist/*.woff2")
+
+  ## Sources
+
+  def inline_js_source(), do: dist_inline_js() |> extract_source!()
+
+  ## Filenames
+
+  def js_filename(), do: dist_js() |> extract_filename!()
+  def css_filename(language), do: dist_css(language) |> extract_filename!()
+
+  ## Helpers
+
+  @doc """
+  Some assets are generated automatically, so we find the revision at runtime.
+  """
+  def rev(output, pattern) do
+    output = Path.expand(output)
+
+    matches =
+      output
+      |> Path.join(pattern)
+      |> Path.wildcard()
+
+    case matches do
+      [] -> raise("could not find matching #{output}/#{pattern}")
+      [asset | _] -> Path.relative_to(asset, output)
+    end
+  end
+
+  defp extract_filename!([{location, _}]), do: location
+  defp extract_source!([{_, source}]), do: source
 end
diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex
@@ -1,6 +1,7 @@
 defmodule ExDoc.Formatter.HTML.Templates do
   @moduledoc false
   require EEx
+  alias ExDoc.Formatter.HTML.Assets
 
   import ExDoc.Utils,
     only: [
@@ -192,28 +193,6 @@ defmodule ExDoc.Formatter.HTML.Templates do
   defp sidebar_type(:livemd), do: "extras"
   defp sidebar_type(:extra), do: "extras"
 
-  defp resolve_asset(output, pattern) do
-    output = Path.expand(output)
-
-    matches =
-      output
-      |> Path.join(pattern)
-      |> Path.wildcard()
-
-    case matches do
-      [] -> raise("could not find matching #{output}/#{pattern}")
-      [asset | _] -> asset
-    end
-  end
-
-  def asset_rev(output, pattern) do
-    resolve_asset(output, pattern) |> Path.relative_to(output)
-  end
-
-  def asset_inline(output, pattern) do
-    resolve_asset(output, pattern) |> File.read!()
-  end
-
   # TODO: Move link_headings and friends to html.ex or even to autolinking code,
   # so content is built with it upfront instead of added at the template level.
 

diff --git a/lib/ex_doc/formatter/html/templates/head_template.eex b/lib/ex_doc/formatter/html/templates/head_template.eex
@@ -13,14 +13,14 @@
       <meta name="robots" content="noindex">
     <% end %>
     <title><%= title %> — <%= config.project %> v<%= config.version %></title>
-    <link rel="stylesheet" href="<%= asset_rev config.output, "dist/html-#{config.proglang}*.css" %>" />
+    <link rel="stylesheet" href="dist/<%= Assets.css_filename(config.proglang) %>" />
     <%= if config.canonical do %>
       <link rel="canonical" href="<%= config.canonical %>" />
     <% end %>
-    <script src="<%= asset_rev config.output, "dist/sidebar_items-*.js" %>"></script>
+    <script src="<%= Assets.rev config.output, "dist/sidebar_items-*.js" %>"></script>
     <script src="docs_config.js"></script>
-    <script async src="<%= asset_rev config.output, "dist/html-*.js" %>"></script>
+    <script async src="dist/<%= Assets.js_filename() %>"></script>
     <%= before_closing_head_tag(config, :html) %>
   </head>
   <body class="sidebar-closed">
-    <script><%= asset_inline config.output, "dist/html_inline-*.js" %></script>
+    <script><%= ExDoc.Formatter.HTML.Assets.inline_js_source() %></script>
diff --git a/lib/ex_doc/formatter/html/templates/search_template.eex b/lib/ex_doc/formatter/html/templates/search_template.eex
@@ -8,5 +8,5 @@
 
   <div class="loading"><div></div><div></div><div></div><div></div></div>
 </div>
-<script src="<%= asset_rev config.output, "dist/search_data*.js" %>"></script>
+<script src="<%= Assets.rev config.output, "dist/search_data*.js" %>"></script>
 <%= footer_template(config, nil) %>