jon.recoil.org
Odoc docs
driver: index only the package's own units
The [ocaml] package's pages root is the compiler's stdlib directory
(lib/ocaml), so sweeping index roots recursively pulled the compiler's
units into its search db, duplicating every stdlib entry in odd
search. Sweep kinds separately, as clean_previous does: pages and
assets recursively under the pages root (they mirror their ids),
module and implementation units from the library directories' top
level only.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
author
Jon Ludlam
co-author
Claude Fable 5
date
(Jul 15, 2026, 4:30 PM +0100)
commit
58790b5e
58790b5ebf3e5ef5c91ea954644899563013458e
parent
bcc0ab5a
bcc0ab5a217eb5063adac7652fd956b05944df56
+68
-42
+5
-4
driver/compile.ml
+5
-4
driver/compile.ml
···
275
275
Sherlodoc.js Fpath.(output_dir // Sherlodoc.js_file);
276
276
let compile_index (index : Odoc_unit.index) =
277
277
let compile_index_one
278
-
({ roots; output_file; json; search_dir = _; sidebar } as index :
278
+
({ pages_root; lib_dirs; output_file; json; search_dir = _; sidebar }
279
+
as index :
279
280
Odoc_unit.index) =
280
281
let () =
281
-
Odoc.compile_index ~json ~occurrence_file ~output_file ~roots
282
-
~simplified:false ~wrap:false ()
282
+
Odoc.compile_index ~json ~occurrence_file ~output_file ~pages_root
283
+
~lib_dirs ~simplified:false ~wrap:false ()
283
284
in
284
285
let sidebar =
285
286
match sidebar with
···
292
293
if simplified_search_output then
293
294
Odoc.compile_index ~json:true ~occurrence_file
294
295
~output_file:Fpath.(output_dir // pkg_dir / "index.js")
295
-
~simplified:true ~wrap:true ~roots ();
296
+
~simplified:true ~wrap:true ~pages_root ~lib_dirs ();
296
297
297
298
Some output_file
298
299
in
+33
-12
driver/odoc.ml
+33
-12
driver/odoc.ml
···
191
191
ignore @@ Cmd_outputs.submit log desc cmd (Some output_file)
192
192
193
193
let compile_index ?(ignore_output = false) ~output_file ?occurrence_file ~json
194
-
~roots ~simplified ~wrap () =
194
+
~pages_root ~lib_dirs ~simplified ~wrap () =
195
195
(* [odoc compile-index] builds one sidebar hierarchy per [--root], so a
196
196
package whose pages root and library directories are separate
197
197
([ocaml-compiler]'s pages in [lib/ocaml-compiler], units in [lib/ocaml])
198
198
would get a split sidebar. Files passed via [--file-list] all land in a
199
-
single group: enumerate the roots' odocls ourselves. *)
199
+
single group: enumerate the odocls ourselves. Pages are swept recursively
200
+
under the pages root (they mirror their ids); module/impl units are taken
201
+
from the library directories' top level only, so a pages root that
202
+
coincides with a shared library directory (the [ocaml] package's is the
203
+
compiler's [lib/ocaml]) doesn't index another package's units. *)
200
204
let file_list = Fpath.(parent output_file / "index-file-list.txt") in
205
+
let is_page f =
206
+
let b = Fpath.basename f in
207
+
Astring.String.is_prefix ~affix:"page-" b
208
+
|| Astring.String.is_prefix ~affix:"asset-" b
209
+
in
201
210
let files =
211
+
let pages =
212
+
match
213
+
Bos.OS.Dir.fold_contents ~elements:`Files
214
+
(fun f acc ->
215
+
if Fpath.has_ext "odocl" f && is_page f then Fpath.Set.add f acc
216
+
else acc)
217
+
Fpath.Set.empty pages_root
218
+
with
219
+
| Ok acc -> acc
220
+
| Error _ -> Fpath.Set.empty
221
+
in
202
222
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
223
+
(fun acc dir ->
224
+
match Bos.OS.Dir.contents dir with
225
+
| Error _ -> acc
226
+
| Ok entries ->
227
+
List.fold_left
228
+
(fun acc f ->
229
+
if Fpath.has_ext "odocl" f && not (is_page f) then
230
+
Fpath.Set.add f acc
231
+
else acc)
232
+
acc entries)
233
+
pages lib_dirs
213
234
in
214
235
let () =
215
236
Util.with_out_to file_list (fun oc ->
+2
-1
driver/odoc.mli
+2
-1
driver/odoc.mli
+11
-4
driver/odoc_unit.ml
+11
-4
driver/odoc_unit.ml
···
47
47
type sidebar = { output_file : Fpath.t; json : bool; pkg_dir : Fpath.t }
48
48
49
49
type index = {
50
-
roots : Fpath.t list;
50
+
pages_root : Fpath.t;
51
+
(* swept recursively for page/asset units: pages mirror their ids *)
52
+
lib_dirs : Fpath.t list;
53
+
(* module/impl units are taken from these directories' top level only:
54
+
a shared directory (lib/ocaml) holds other packages' pages, and a
55
+
pages root that coincides with one (the [ocaml] package's is the
56
+
compiler's stdlib directory) must not sweep foreign units *)
51
57
output_file : Fpath.t;
52
58
json : bool;
53
59
search_dir : Fpath.t;
···
57
63
58
64
let pp_index fmt x =
59
65
Format.fprintf fmt
60
-
"@[<hov>roots: %a@;output_file: %a@;json: %b@;search_dir: %a@]"
61
-
(Fmt.list Fpath.pp) x.roots Fpath.pp x.output_file x.json Fpath.pp
62
-
x.search_dir
66
+
"@[<hov>pages_root: %a@;lib_dirs: %a@;output_file: %a@;json: %b@;\
67
+
search_dir: %a@]"
68
+
Fpath.pp x.pages_root (Fmt.list Fpath.pp) x.lib_dirs Fpath.pp x.output_file
69
+
x.json Fpath.pp x.search_dir
63
70
64
71
type 'a t = {
65
72
parent_id : Odoc.Id.t;
+4
-1
driver/odoc_unit.mli
+4
-1
driver/odoc_unit.mli
···
21
21
22
22
type sidebar = { output_file : Fpath.t; json : bool; pkg_dir : Fpath.t }
23
23
type index = {
24
-
roots : Fpath.t list;
24
+
pages_root : Fpath.t;
25
+
(** swept recursively for page/asset units (pages mirror their ids) *)
26
+
lib_dirs : Fpath.t list;
27
+
(** module/impl units come from these directories' top level only *)
25
28
output_file : Fpath.t;
26
29
json : bool;
27
30
search_dir : Fpath.t;
+13
-20
driver/odoc_units_of.ml
+13
-20
driver/odoc_units_of.ml
···
182
182
in
183
183
184
184
let index_of pkg =
185
-
(* Linked units live under the package's pages root ([lib/<pkg>], which
186
-
usually also holds the main library's units) and in the library dirs.
187
-
Roots are scanned recursively: prune roots nested inside another (a
188
-
sublibrary's dir under [lib/<pkg>]) or their units would be indexed
189
-
twice, which breaks the sherlodoc db build. *)
190
-
let roots =
191
-
let all =
192
-
Fpath.( // ) lib_root (doc_dir pkg)
193
-
:: List.map (fun (lib : Packages.libty) -> lib.dir) pkg.libraries
194
-
|> List.map Fpath.to_dir_path
195
-
|> List.sort_uniq Fpath.compare
196
-
in
197
-
List.filter
198
-
(fun d ->
199
-
not
200
-
(List.exists
201
-
(fun d' -> (not (Fpath.equal d d')) && Fpath.is_prefix d' d)
202
-
all))
203
-
all
185
+
(* Pages are swept recursively under the package's pages root; module and
186
+
implementation units are taken from the library directories' top level
187
+
only, so a pages root that coincides with a shared library directory
188
+
(the [ocaml] package's is the compiler's [lib/ocaml]) doesn't sweep
189
+
another package's units into this package's index and search db. *)
190
+
let pages_root = Fpath.( // ) lib_root (doc_dir pkg) in
191
+
let lib_dirs =
192
+
List.map
193
+
(fun (lib : Packages.libty) -> Fpath.to_dir_path lib.dir)
194
+
pkg.libraries
195
+
|> List.sort_uniq Fpath.compare
204
196
in
205
197
let output_file = Fpath.(index_dir / pkg.name / Odoc.index_filename) in
206
198
let pkg_dir = doc_dir pkg in
···
209
201
{ output_file; json = false; pkg_dir }
210
202
in
211
203
{
212
-
roots;
204
+
pages_root;
205
+
lib_dirs;
213
206
output_file;
214
207
json = false;
215
208
search_dir = doc_dir pkg;