odoc: Put support files in their own directory (#6913)

* odoc: Put support files in their own directory odoc 2.2 added math support, which comes with extra javascript, css and font files. Rather than add these as explicit targets, this commit changes the invocation of `odoc support-files` to output into the dir `_build/default/_doc/_html/_odoc_support` as a directory target. Signed-off-by: Jon Ludlam <jon@recoil.org> * Set directory targets for the _odoc_support dir Signed-off-by: Jon Ludlam <jon@recoil.org> * More directory rules fixes for odoc Signed-off-by: Jon Ludlam <jon@recoil.org> * Formatting Signed-off-by: Jon Ludlam <jon@recoil.org> * Factor out constant Signed-off-by: Jon Ludlam <jon@recoil.org> * Update CHANGES Signed-off-by: Jon Ludlam <jon@recoil.org> --------- Signed-off-by: Jon Ludlam <jon@recoil.org>
ocaml · Feb 8, 2023 · 1d5ce4a · 1d5ce4a
1 parent 06dde72
commit 1d5ce4a
Show file tree

Hide file tree

Showing 6 changed files with 36 additions and 22 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,5 +1,6 @@
 Unreleased
 ----------
+- Fix handling of support files generated by odoc. (#6913, @jonludlam)
 
 - Fix parsing of OCaml errors that contain code excerpts with `...` in them.
   (#7008, @rgrinberg)

diff --git a/src/dune_rules/odoc.ml b/src/dune_rules/odoc.ml
@@ -85,6 +85,8 @@ let add_rule sctx =
   Super_context.add_rule sctx ~dir
 
 module Paths = struct
+  let odoc_support_dirname = "_odoc_support"
+
   let root (context : Context.t) =
     Path.Build.relative context.Context.build_dir "_doc"
 
@@ -111,9 +113,7 @@ module Paths = struct
 
   let gen_mld_dir ctx pkg = root ctx ++ "_mlds" ++ Package.Name.to_string pkg
 
-  let css_file ctx = html_root ctx ++ "odoc.css"
-
-  let highlight_pack_js ctx = html_root ctx ++ "highlight.pack.js"
+  let odoc_support ctx = html_root ctx ++ odoc_support_dirname
 
   let toplevel_index ctx = html_root ctx ++ "index.html"
 end
@@ -347,12 +347,21 @@ let setup_html sctx (odoc_file : odoc_artefact) =
       (odoc_file.html_dir, [ dummy ])
   in
   let open Memo.O in
+  let odoc_support_path = Paths.odoc_support ctx in
+  let html_output = Paths.html_root ctx in
+  let support_relative =
+    Path.reach (Path.build odoc_support_path) ~from:(Path.build html_output)
+  in
   let* run_odoc =
     run_odoc sctx
       ~dir:(Path.build (Paths.html_root ctx))
       "html-generate" ~flags_for:None
       [ A "-o"
       ; Path (Path.build (Paths.html_root ctx))
+      ; A "--support-uri"
+      ; A support_relative
+      ; A "--theme-uri"
+      ; A support_relative
       ; Dep (Path.build odoc_file.odocl_file)
       ; Hidden_targets [ odoc_file.html_file ]
       ]
@@ -371,13 +380,15 @@ let setup_html sctx (odoc_file : odoc_artefact) =
 let setup_css_rule sctx =
   let open Memo.O in
   let ctx = Super_context.context sctx in
+  let dir = Paths.odoc_support ctx in
   let* run_odoc =
-    run_odoc sctx ~dir:(Path.build ctx.build_dir) "support-files"
-      ~flags_for:None
-      [ A "-o"
-      ; Path (Path.build (Paths.html_root ctx))
-      ; Hidden_targets [ Paths.css_file ctx; Paths.highlight_pack_js ctx ]
-      ]
+    let+ cmd =
+      run_odoc sctx ~dir:(Path.build ctx.build_dir) "support-files"
+        ~flags_for:None
+        [ A "-o"; Path (Path.build dir) ]
+    in
+    cmd
+    |> Action_builder.With_targets.add_directories ~directory_targets:[ dir ]
   in
   add_rule sctx run_odoc
 
@@ -404,7 +415,7 @@ let setup_toplevel_index_rule sctx =
 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>index</title>
-    <link rel="stylesheet" href="./odoc.css"/>
+    <link rel="stylesheet" href="./%s/odoc.css"/>
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
   </head>
@@ -419,7 +430,7 @@ let setup_toplevel_index_rule sctx =
     </main>
   </body>
 </html>|}
-      list_items
+      Paths.odoc_support_dirname list_items
   in
   let ctx = Super_context.context sctx in
   add_rule sctx (Action_builder.write_file (Paths.toplevel_index ctx) html)
@@ -495,7 +506,7 @@ let create_odoc ctx ~target odoc_file =
 
 let static_html ctx =
   let open Paths in
-  [ css_file ctx; highlight_pack_js ctx; toplevel_index ctx ]
+  [ odoc_support ctx; toplevel_index ctx ]
 
 let check_mlds_no_dupes ~pkg ~mlds =
   match
@@ -786,14 +797,11 @@ let setup_private_library_doc_alias sctx ~scope ~dir (l : Dune_file.Library.t) =
     Rules.Produce.Alias.add_deps (Alias.private_doc ~dir)
       (lib |> Dep.html_alias ctx |> Dune_engine.Dep.alias |> Action_builder.dep)
 
-let has_rules m =
+let has_rules ?(directory_targets = Path.Build.Map.empty) m =
   let rules = Rules.collect_unit (fun () -> m) in
   Memo.return
     (Build_config.Rules
-       { rules
-       ; build_dir_only_sub_dirs = Subdir_set.empty
-       ; directory_targets = Path.Build.Map.empty
-       })
+       { rules; build_dir_only_sub_dirs = Subdir_set.empty; directory_targets })
 
 let with_package pkg ~f =
   let pkg = Package.Name.of_string pkg in
@@ -818,7 +826,12 @@ let gen_rules sctx ~dir:_ rest =
          ; directory_targets = Path.Build.Map.empty
          })
   | [ "_html" ] ->
-    has_rules (setup_css_rule sctx >>> setup_toplevel_index_rule sctx)
+    let ctx = Super_context.context sctx in
+    let directory_targets =
+      Path.Build.Map.singleton (Paths.odoc_support ctx) Loc.none
+    in
+    has_rules ~directory_targets
+      (setup_css_rule sctx >>> setup_toplevel_index_rule sctx)
   | [ "_mlds"; pkg ] ->
     with_package pkg ~f:(fun pkg ->
         let* _mlds, rules = package_mlds sctx ~pkg in

diff --git a/test/blackbox-tests/test-cases/odoc/multiple-private-libs.t/run.t b/test/blackbox-tests/test-cases/odoc/multiple-private-libs.t/run.t
@@ -1,7 +1,7 @@
 This test checks that there is no clash when two private libraries have the same name
 
   $ dune build --display short @doc-private
-          odoc _doc/_html/highlight.pack.js,_doc/_html/odoc.css
+          odoc _doc/_html/_odoc_support
         ocamlc a/.test.objs/byte/test.{cmi,cmo,cmt}
         ocamlc b/.test.objs/byte/test.{cmi,cmo,cmt}
           odoc a/.test.objs/byte/test.odoc

diff --git a/test/blackbox-tests/test-cases/odoc/odoc-simple.t/run.t b/test/blackbox-tests/test-cases/odoc/odoc-simple.t/run.t
@@ -16,7 +16,7 @@ This test if `.odocl` files are generated
   <html xmlns="http://www.w3.org/1999/xhtml">
     <head>
       <title>index</title>
-      <link rel="stylesheet" href="./odoc.css"/>
+      <link rel="stylesheet" href="./_odoc_support/odoc.css"/>
       <meta charset="utf-8"/>
       <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
     </head>

diff --git a/test/blackbox-tests/test-cases/odoc/odoc-unique-mlds/diff-scope.t/run.t b/test/blackbox-tests/test-cases/odoc/odoc-unique-mlds/diff-scope.t/run.t
@@ -1,6 +1,6 @@
 Duplicate mld's in different scope
   $ dune build @doc --display short
-          odoc _doc/_html/highlight.pack.js,_doc/_html/odoc.css
+          odoc _doc/_html/_odoc_support
           odoc _doc/_odoc/pkg/scope1/page-index.odoc
         ocamlc scope1/.scope1.objs/byte/scope1.{cmi,cmo,cmt}
           odoc _doc/_odoc/pkg/scope2/page-index.odoc

diff --git a/test/blackbox-tests/test-cases/odoc/odoc-unique-mlds/same-scope.t/run.t b/test/blackbox-tests/test-cases/odoc/odoc-unique-mlds/same-scope.t/run.t
@@ -1,6 +1,6 @@
 Duplicate mld's in the same scope
   $ dune build @doc --display short
-          odoc _doc/_html/highlight.pack.js,_doc/_html/odoc.css
+          odoc _doc/_html/_odoc_support
           odoc _doc/_odoc/pkg/root/page-index.odoc
         ocamlc lib1/.root_lib1.objs/byte/root_lib1.{cmi,cmo,cmt}
         ocamlc lib2/.root_lib2.objs/byte/root_lib2.{cmi,cmo,cmt}