CLI for generating source: invert source and impl order

Source is now the positional argument, while impl is passed as an argument. When
we generate source for other files (such as dune or .mli or Makefiles or ...)
this will come handy.

Author: panglesd

src/odoc/bin/main.ml

@@ -774,11 +774,11 @@ module Make_renderer (R : S) : sig
 
   val targets : docs:string -> unit Term.t * Term.info
 
-  val targets_impl : docs:string -> unit Term.t * Term.info
+  val targets_source : docs:string -> unit Term.t * Term.info
 
   val generate : docs:string -> unit Term.t * Term.info
 
-  val generate_impl : docs:string -> unit Term.t * Term.info
+  val generate_source : docs:string -> unit Term.t * Term.info
 end = struct
   let input_odoc =
     let doc = "Input file." in
@@ -862,19 +862,25 @@ end = struct
 
   let generate ~docs = Generate.(cmd, info ~docs)
 
-  module Generate_impl = struct
+  module Generate_source = struct
     let generate extra _hidden output_dir syntax extra_suffix input_file
         warnings_options source_file =
-      let file = Fs.File.of_string input_file in
-      Rendering.generate_impl_odoc ~renderer:R.renderer ~warnings_options
-        ~syntax ~output:output_dir ~extra_suffix ~source_file extra file
+      Rendering.generate_source_odoc ~renderer:R.renderer ~warnings_options
+        ~syntax ~output:output_dir ~extra_suffix ~source_file extra input_file
+
+    let input_odocl =
+      let doc = "Linked implementation file." in
+      Arg.(
+        required
+        & opt (some convert_fpath) None
+        & info [ "impl" ] ~doc ~docv:"impl-file.odocl")
 
     let source_file =
       let doc = "Source code for the implementation unit." in
       Arg.(
-        value
-        & opt (some convert_fpath) None
-        & info [ "source" ] ~doc ~docv:"file.ml")
+        required
+        & pos 0 (some convert_fpath) None
+        & info ~doc ~docv:"FILE.ml" [])
 
     let cmd =
       let syntax =
@@ -895,10 +901,10 @@ end = struct
         Format.sprintf "Generate %s files from a $(i,impl-*.odocl)."
           R.renderer.name
       in
-      Term.info ~docs ~doc (R.renderer.name ^ "-generate-impl")
+      Term.info ~docs ~doc (R.renderer.name ^ "-generate-source")
   end
 
-  let generate_impl ~docs = Generate_impl.(cmd, info ~docs)
+  let generate_source ~docs = Generate_source.(cmd, info ~docs)
 
   module Targets = struct
     let list_targets output_dir directories extra odoc_file =
@@ -940,16 +946,16 @@ end = struct
 
   let targets ~docs = Targets.(cmd, info ~docs)
 
-  module Targets_impl = struct
+  module Targets_source = struct
     let list_targets output_dir source_file extra odoc_file =
-      let odoc_file = Fs.File.of_string odoc_file in
       let warnings_options =
         { Odoc_model.Error.warn_error = false; print_warnings = false }
       in
-      Rendering.targets_impl_odoc ~warnings_options ~syntax:OCaml
+      Rendering.targets_source_odoc ~warnings_options ~syntax:OCaml
         ~renderer:R.renderer ~output:output_dir ~extra ~source_file odoc_file
 
-    let source_file = Generate_impl.source_file
+    let source_file = Generate_source.source_file
+    let input_odocl = Generate_source.input_odocl
 
     let cmd =
       Term.(
@@ -960,13 +966,13 @@ end = struct
     let info ~docs =
       let doc =
         Format.sprintf
-          "Print the files that would be generated by $(i,%s-generate-impl)."
+          "Print the files that would be generated by $(i,%s-generate-source)."
           R.renderer.name
       in
-      Term.info (R.renderer.name ^ "-targets-impl") ~docs ~doc
+      Term.info (R.renderer.name ^ "-targets-source") ~docs ~doc
   end
 
-  let targets_impl ~docs = Targets_impl.(cmd, info ~docs)
+  let targets_source ~docs = Targets_source.(cmd, info ~docs)
 end
 
 module Odoc_latex_url : sig
@@ -1528,7 +1534,7 @@ let () =
       Compile_asset.(cmd, info ~docs:section_pipeline);
       Odoc_link.(cmd, info ~docs:section_pipeline);
       Odoc_html.generate ~docs:section_pipeline;
-      Odoc_html.generate_impl ~docs:section_pipeline;
+      Odoc_html.generate_source ~docs:section_pipeline;
       Support_files_command.(cmd, info ~docs:section_pipeline);
       Compile_impl.(cmd, info ~docs:section_pipeline);
       Indexing.(cmd, info ~docs:section_pipeline);
@@ -1539,7 +1545,7 @@ let () =
       Targets.Support_files.(cmd, info ~docs:section_support);
       Odoc_error.(cmd, info ~docs:section_support);
       Odoc_html.targets ~docs:section_support;
-      Odoc_html.targets_impl ~docs:section_support;
+      Odoc_html.targets_source ~docs:section_support;
       Odoc_manpage.targets ~docs:section_support;
       Odoc_latex.targets ~docs:section_support;
       Depends.Compile.(cmd, info ~docs:section_support);

src/odoc/rendering.ml

@@ -96,9 +96,9 @@ let generate_odoc ~syntax ~warnings_options ~renderer ~output ~extra_suffix
     docs;
   Ok ()
 
-let documents_of_implementation ~warnings_options:_ ~syntax impl source =
-  match (source, impl.Lang.Implementation.id) with
-  | Some source_file, Some _ -> (
+let documents_of_implementation ~warnings_options:_ ~syntax impl source_file =
+  match impl.Lang.Implementation.id with
+  | Some _ -> (
       match Fs.File.read source_file with
       | Error (`Msg msg) ->
           Error (`Msg (Format.sprintf "Couldn't load source file: %s" msg))
@@ -111,16 +111,11 @@ let documents_of_implementation ~warnings_options:_ ~syntax impl source =
               syntax_info source_code
           in
           Ok rendered)
-  | _, None ->
+  | None ->
       Error (`Msg "The implementation unit was not compiled with --source-id.")
-  | None, _ ->
-      Error
-        (`Msg
-          "--source should be passed when generating documents for an \
-           implementation.")
 
-let generate_impl_odoc ~syntax ~warnings_options ~renderer ~output ~source_file
-    ~extra_suffix extra file =
+let generate_source_odoc ~syntax ~warnings_options ~renderer ~output
+    ~source_file ~extra_suffix extra file =
   Odoc_file.load file >>= fun unit ->
   match unit.content with
   | Odoc_file.Impl_content impl ->
@@ -151,7 +146,7 @@ let targets_odoc ~resolver ~warnings_options ~syntax ~renderer ~output:root_dir
     docs;
   Ok ()
 
-let targets_impl_odoc ~syntax ~warnings_options ~renderer ~output:root_dir
+let targets_source_odoc ~syntax ~warnings_options ~renderer ~output:root_dir
     ~extra ~source_file odoctree =
   Odoc_file.load odoctree >>= fun unit ->
   match unit.content with

src/odoc/rendering.mli

@@ -22,12 +22,12 @@ val generate_odoc :
   Fpath.t ->
   (unit, [> msg ]) result
 
-val generate_impl_odoc :
+val generate_source_odoc :
   syntax:Renderer.syntax ->
   warnings_options:Odoc_model.Error.warnings_options ->
   renderer:'a Renderer.t ->
   output:Fs.directory ->
-  source_file:Fpath.t option ->
+  source_file:Fpath.t ->
   extra_suffix:string option ->
   'a ->
   Fpath.t ->
@@ -43,12 +43,12 @@ val targets_odoc :
   Fpath.t ->
   (unit, [> msg ]) result
 
-val targets_impl_odoc :
+val targets_source_odoc :
   syntax:Renderer.syntax ->
   warnings_options:Odoc_model.Error.warnings_options ->
   renderer:'a Renderer.t ->
   output:Fs.directory ->
   extra:'a ->
-  source_file:Fpath.t option ->
+  source_file:Fpath.t ->
   Fs.file ->
   (unit, [> Or_error.msg ]) result

test/integration/json_expansion_with_sources.t/run.t

@@ -23,18 +23,18 @@ Test the JSON output in the presence of expanded modules.
   html/Main/index.html.json
   html/Main/A/index.html.json
   html/Main/A/B/index.html.json
-  $ odoc html-targets-impl --source a.ml -o html impl-main__A.odocl
+  $ odoc html-targets-source --impl impl-main__A.odocl -o html a.ml
   html/src/a.ml.html
-  $ odoc html-targets-impl --source main.ml -o html impl-main.odocl
+  $ odoc html-targets-source --impl impl-main.odocl -o html main.ml
   html/src/main.ml.html
-  $ odoc html-targets-impl --source a.ml --as-json -o html impl-main__A.odocl
+  $ odoc html-targets-source --impl impl-main__A.odocl --as-json -o html a.ml
   html/src/a.ml.html.json
-  $ odoc html-targets-impl --source main.ml --as-json -o html impl-main.odocl
+  $ odoc html-targets-source --impl impl-main.odocl --as-json -o html main.ml
   html/src/main.ml.html.json
 
-  $ odoc html-generate-impl --source a.ml --as-json -o html impl-main__A.odocl
+  $ odoc html-generate-source --impl impl-main__A.odocl --as-json -o html a.ml
   $ odoc html-generate --as-json -o html main__A.odocl
-  $ odoc html-generate-impl --source main.ml --as-json -o html impl-main.odocl
+  $ odoc html-generate-source --impl impl-main.odocl --as-json -o html main.ml
   $ odoc html-generate --as-json -o html main.odocl
 
   $ cat html/Main/index.html.json

test/sources/double_wrapped.t/run.t

@@ -20,8 +20,8 @@ Similar to the lookup_def_wrapped test.
   $ odoc link -I . main__.odoc
 
   $ odoc html-generate --indent -o html main.odocl
-  $ odoc html-generate-impl --source main.ml --indent -o html impl-main.odocl
-  $ odoc html-generate-impl --source a.ml --indent -o html impl-main__A.odocl
+  $ odoc html-generate-source --impl impl-main.odocl --indent -o html main.ml
+  $ odoc html-generate-source --impl impl-main__A.odocl --indent -o html a.ml
 
 Look if all the source files are generated:
 

test/sources/functor.t/run.t

@@ -15,11 +15,11 @@ Verify the behavior on functors.
   $ odoc link -I . impl-s.odoc
   $ odoc link -I . impl-a.odoc
   $ odoc link -I . impl-b.odoc
-  $ odoc html-generate-impl --source s.ml --indent -o html impl-s.odocl
+  $ odoc html-generate-source --impl impl-s.odocl --indent -o html s.ml
   $ odoc html-generate --indent -o html s.odocl
-  $ odoc html-generate-impl --source a.ml --indent -o html impl-a.odocl
+  $ odoc html-generate-source --impl impl-a.odocl --indent -o html a.ml
   $ odoc html-generate --indent -o html a.odocl
-  $ odoc html-generate-impl --source b.ml --indent -o html impl-b.odocl
+  $ odoc html-generate-source --impl impl-b.odocl --indent -o html b.ml
   $ odoc html-generate --indent -o html b.odocl
 
   $ find html | sort

test/sources/include_in_expansion.t/run.t

@@ -18,9 +18,9 @@ Checking that source parents are kept, using include.
   $ odoc link -I . impl-main.odoc
   $ odoc link -I . impl-main__A.odoc
 
-  $ odoc html-generate-impl --source main.ml --indent -o html impl-main.odocl
+  $ odoc html-generate-source --impl impl-main.odocl --indent -o html main.ml
   $ odoc html-generate --indent -o html main.odocl
-  $ odoc html-generate-impl --source a.ml --hidden --indent -o html impl-main__A.odocl
+  $ odoc html-generate-source --impl impl-main__A.odocl --hidden --indent -o html a.ml
   $ odoc html-generate --hidden --indent -o html main__A.odocl
 
 In Main.A, the source parent of value x should be to Main__A, while the

test/sources/lookup_def_wrapped.t/run.t

@@ -21,11 +21,11 @@ It's a simpler case than Dune's wrapping.
   $ odoc link -I . impl-main.odoc
   $ odoc link -I . main.odoc
 
-  $ odoc html-generate-impl --source main.ml --indent -o html impl-main.odocl
+  $ odoc html-generate-source --impl impl-main.odocl --indent -o html main.ml
   $ odoc html-generate --indent -o html main.odocl
-  $ odoc html-generate-impl --source a.ml --indent -o html impl-main__A.odocl
+  $ odoc html-generate-source --impl impl-main__A.odocl --indent -o html a.ml
   $ odoc html-generate --hidden --indent -o html main__A.odocl
-  $ odoc html-generate-impl --source b.ml --indent -o html impl-main__B.odocl
+  $ odoc html-generate-source --impl impl-main__B.odocl --indent -o html b.ml
   $ odoc html-generate --hidden --indent -o html main__B.odocl
 
 Look if all the source files are generated:

test/sources/recursive_module.t/run.t

@@ -7,6 +7,10 @@ Checking that source links exists inside recursive modules.
   $ odoc link -I . main.odoc
   $ odoc html-generate --indent -o html main.odocl
   $ odoc html-generate-impl --source main.ml --indent -o html impl-main.odocl
+  odoc: unknown command 'html-generate-impl', must be one of 'aggregate-occurrences', 'classify', 'compile', 'compile-asset', 'compile-deps', 'compile-impl', 'compile-index', 'compile-targets', 'count-occurrences', 'css', 'errors', 'html', 'html-deps', 'html-fragment', 'html-generate', 'html-generate-source', 'html-targets', 'html-targets-source', 'html-url', 'latex', 'latex-generate', 'latex-targets', 'latex-url', 'link', 'link-deps', 'man', 'man-generate', 'man-targets', 'support-files' or 'support-files-targets'.
+  Usage: odoc [COMMAND] …
+  Try 'odoc --help' for more information.
+  [2]
 
 Both modules should contain source links
 

test/sources/single_mli.t/run.t

@@ -14,9 +14,9 @@ Similar to Astring library.
   $ odoc link -I . impl-a.odoc
   $ odoc link -I . a.odoc
 
-  $ odoc html-generate-impl --source a_x.ml --indent -o html impl-a_x.odocl
+  $ odoc html-generate-source --impl impl-a_x.odocl --indent -o html a_x.ml
   $ odoc html-generate --indent -o html a_x.odocl
-  $ odoc html-generate-impl --source a.ml --indent -o html impl-a.odocl
+  $ odoc html-generate-source --impl impl-a.odocl --indent -o html a.ml
   $ odoc html-generate --indent -o html a.odocl
 
 Look if all the source files are generated: