Disable the missing root warning by default

It can be re-enabled via the command-line option

    --enable-missing-root-warning

But since this is usually a build system issue rather than something
end-users will need to worry about, let's not complain about it.

Note that this will _not_ suppress warnings generated if references
aren't resolved - so if you explicitly have a reference to something
in a dependency library and it's not found when linking, you'll still
get a warning.

Fixes: #825

Author: jonludlam

src/model/error.ml

@@ -1,5 +1,7 @@
 open Result
 
+let enable_missing_root_warning = ref false
+
 type full_location_payload = Odoc_parser.Warning.t = {
   location : Location_.span;
   message : string;

src/model/error.mli

@@ -1,5 +1,7 @@
 type t
 
+val enable_missing_root_warning : bool ref
+
 val make :
   ?suggestion:string ->
   ('a, Format.formatter, unit, Location_.span -> t) format4 ->

src/odoc/bin/main.ml

@@ -82,10 +82,20 @@ let warnings_options =
     let env = Arg.env_var "ODOC_PRINT_WARNINGS" ~doc in
     Arg.(value & opt bool true & info ~docs ~doc ~env [ "print-warnings" ])
   in
+  let enable_missing_root_warning =
+    let doc =
+      "Produce a warning when a root is missing. This is usually a build \
+       system problem so is disabled for users by default."
+    in
+    let env = Arg.env_var "ODOC_ENABLE_MISSING_ROOT_WARNING" ~doc in
+    Arg.(value & flag & info ~docs ~doc ~env [ "enable-missing-root-warning" ])
+  in
   Term.(
-    const (fun warn_error print_warnings ->
+    const (fun warn_error print_warnings enable_missing_root_warning ->
+        Odoc_model.Error.enable_missing_root_warning :=
+          enable_missing_root_warning;
         { Odoc_model.Error.warn_error; print_warnings })
-    $ warn_error $ print_warnings)
+    $ warn_error $ print_warnings $ enable_missing_root_warning)
 
 let dst ?create () =
   let doc = "Output directory where the HTML tree is expected to be saved." in

src/xref2/lookup_failures.ml

@@ -59,7 +59,8 @@ let raise_warnings ~filename failures =
 let catch_failures ~filename f =
   let r, failures = with_ref acc [] f in
   Error.catch_warnings (fun () ->
-      raise_root_errors ~filename failures;
+      if !Error.enable_missing_root_warning then
+        raise_root_errors ~filename failures;
       raise_warnings ~filename failures;
       r)
 

test/xref2/multi_file_module_type_of.t/run.t

@@ -26,15 +26,15 @@ In this instance, module S will not be expanded because we are not providing an
 odoc file for `Test0` - so there will be a warning when we run `odoc compile`
 on test1.cmti:
 
-  $ odoc compile --package foo test1.cmti
+  $ odoc compile --package foo test1.cmti --enable-missing-root-warning
   File "test1.cmti":
   Warning: Couldn't find the following modules:
     Test0
 
 Similarly, module `T` also can not be expanded, therefore we expect
 another warning when we run `odoc compile` on test2.cmti:
 
-  $ odoc compile --package foo test2.cmti -I .
+  $ odoc compile --package foo test2.cmti -I . --enable-missing-root-warning
   File "test2.cmti":
   Warning: Couldn't find the following modules:
     Test1

test/xref2/unexpanded_module_type_of.t/run.t

@@ -15,7 +15,7 @@ This is a test for [this issue](https://github.com/ocaml/odoc/issues/500)
 Compiling an odoc file for `test` without compiling one for `test0` 
 should _not_ result in an exception, merely a warning.
 
-  $ odoc compile --package test test.cmti
+  $ odoc compile --package test test.cmti --enable-missing-root-warning
   File "test.cmti":
   Warning: Couldn't find the following modules:
     Test0

test/xref2/warnings.t/run.t

@@ -28,7 +28,7 @@ A contains both parsing errors and a reference to B that isn't compiled yet:
 
 A contains linking errors:
 
-  $ odoc link a.odoc
+  $ odoc link a.odoc --enable-missing-root-warning
   File "a.odoc":
   Warning: Couldn't find the following modules:
     B