jon.recoil.org
Odoc docs
driver: feed compile-index a file list, not roots
odoc compile-index builds one sidebar hierarchy per --root, so a
package whose pages root and library directories are separate — the
compiler's pages live in lib/ocaml-compiler, its units in lib/ocaml —
got a split sidebar: page entries in one tree, module groups in
another. Files passed via --file-list all land in a single group, so
enumerate the roots' odocls ourselves and pass the list; the sidebar
is again byte-identical to the pre-colocation driver's.
Found by diffing the rendered HTML of 16 packages against main.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
author
Jon Ludlam
co-author
Claude Fable 5
date
(Jul 15, 2026, 3:01 PM +0100)
commit
bcc0ab5a
bcc0ab5a217eb5063adac7652fd956b05944df56
parent
dfaf641e
dfaf641ef639c35940b4754f0ae1e9f25eec20e1
+26
-2
+26
-2
driver/odoc.ml
+26
-2
driver/odoc.ml
···
192
192
193
193
let compile_index ?(ignore_output = false) ~output_file ?occurrence_file ~json
194
194
~roots ~simplified ~wrap () =
195
-
let roots =
196
-
List.fold_left (fun c r -> Cmd.(c % "--root" % p r)) Cmd.empty roots
195
+
(* [odoc compile-index] builds one sidebar hierarchy per [--root], so a
196
+
package whose pages root and library directories are separate
197
+
([ocaml-compiler]'s pages in [lib/ocaml-compiler], units in [lib/ocaml])
198
+
would get a split sidebar. Files passed via [--file-list] all land in a
199
+
single group: enumerate the roots' odocls ourselves. *)
200
+
let file_list = Fpath.(parent output_file / "index-file-list.txt") in
201
+
let files =
202
+
List.fold_left
203
+
(fun acc root ->
204
+
match
205
+
Bos.OS.Dir.fold_contents ~elements:`Files
206
+
(fun f acc ->
207
+
if Fpath.has_ext "odocl" f then Fpath.Set.add f acc else acc)
208
+
acc root
209
+
with
210
+
| Ok acc -> acc
211
+
| Error _ -> acc)
212
+
Fpath.Set.empty roots
197
213
in
214
+
let () =
215
+
Util.with_out_to file_list (fun oc ->
216
+
Fpath.Set.iter
217
+
(fun f -> Printf.fprintf oc "%s\n" (Fpath.to_string f))
218
+
files)
219
+
|> Result.get_ok
220
+
in
221
+
let roots = Cmd.(v "--file-list" % p file_list) in
198
222
let json = if json then Cmd.v "--json" else Cmd.empty in
199
223
let simplified =
200
224
if simplified then Cmd.v "--simplified-json" else Cmd.empty