Adding an html-generate-impl command

Author: panglesd

src/odoc/bin/main.ml

@@ -775,6 +775,8 @@ module Make_renderer (R : S) : sig
   val targets : 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
 end = struct
   let input_odoc =
     let doc = "Input file." in
@@ -858,6 +860,43 @@ end = struct
 
   let generate ~docs = Generate.(cmd, info ~docs)
 
+  module Generate_impl = 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
+
+    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")
+
+    let cmd =
+      let syntax =
+        let doc = "Available options: ml | re" in
+        let env = Arg.env_var "ODOC_SYNTAX" in
+        Arg.(
+          value
+          & opt (pconv convert_syntax) Odoc_document.Renderer.OCaml
+            @@ info ~docv:"SYNTAX" ~doc ~env [ "syntax" ])
+      in
+      Term.(
+        const handle_error
+        $ (const generate $ R.extra_args $ hidden $ dst ~create:true () $ syntax
+         $ extra_suffix $ input_odocl $ warnings_options $ source_file))
+
+    let info ~docs =
+      let doc =
+        Format.sprintf "Generate %s files from a $(i,.odocl)." R.renderer.name
+      in
+      Term.info ~docs ~doc (R.renderer.name ^ "-generate-impl")
+  end
+
+  let generate_impl ~docs = Generate_impl.(cmd, info ~docs)
+
   module Targets = struct
     let list_targets output_dir directories extra odoc_file =
       let odoc_file = Fs.File.of_string odoc_file in
@@ -1458,6 +1497,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;
       Support_files_command.(cmd, info ~docs:section_pipeline);
       Compile_impl.(cmd, info ~docs:section_pipeline);
       Indexing.(cmd, info ~docs:section_pipeline);

src/odoc/rendering.ml

@@ -15,37 +15,17 @@ let documents_of_page ~warnings_options ~syntax ~renderer ~extra page =
   |> Error.handle_warnings ~warnings_options
   >>= fun extra_docs -> Ok (Renderer.document_of_page ~syntax page :: extra_docs)
 
-(* let documents_of_implementation ~warnings_options:_ ~syntax impl source = *)
-(*   match (source, impl.Lang.Implementation.id) with *)
-(*   | Some source_file, Some _ -> ( *)
-(*       match Fs.File.read source_file with *)
-(*       | Error (`Msg msg) -> *)
-(*           Error (`Msg (Format.sprintf "Couldn't load source file: %s" msg)) *)
-(*       | Ok source_code -> *)
-(*           let syntax_info = *)
-(*             Syntax_highlighter.syntax_highlighting_locs source_code *)
-(*           in *)
-(*           let rendered = *)
-(*             Odoc_document.Renderer.documents_of_implementation ~syntax impl *)
-(*               syntax_info source_code *)
-(*           in *)
-(*           Ok rendered) *)
-(*   | _, None -> *)
-(*       Error (`Msg "The implementation unit was not compiled with --source-id.") *)
-(*   | None, _ -> *)
-(*       Error *)
-(*         (`Msg *)
-(* "--source or --source-root should be passed when generating \ *)
-   (*            documents for an implementation.") *)
-
 let documents_of_odocl ~warnings_options ~renderer ~extra ~syntax input =
   Odoc_file.load input >>= fun unit ->
   match unit.content with
   | Odoc_file.Page_content odoctree ->
       documents_of_page ~warnings_options ~syntax ~renderer ~extra odoctree
   | Impl_content _impl ->
       (* documents_of_implementation ~warnings_options ~syntax impl source *)
-      failwith "TODO ERROR"
+      Error
+        (`Msg
+          "Wrong kind of unit: Expected a page or module unit, got an \
+           implementation. Use the dedicated command for implementation.")
   | Unit_content odoctree ->
       documents_of_unit ~warnings_options ~syntax ~renderer ~extra odoctree
   | Asset_content _ -> Ok [] (* TODO *)
@@ -56,8 +36,10 @@ let documents_of_input ~renderer ~extra ~resolver ~warnings_options ~syntax
   Odoc_link.from_odoc ~resolver ~warnings_options input output >>= function
   | `Page page -> Ok [ Renderer.document_of_page ~syntax page ]
   | `Impl _impl ->
-      (* Ok (Renderer.documents_of_implementation ~syntax impl [] "") *)
-      failwith "TODO ERROR"
+      Error
+        (`Msg
+          "Wrong kind of unit: Expected a page or module unit, got an \
+           implementation. Use the dedicated command for implementation.")
   | `Module m -> documents_of_unit ~warnings_options ~syntax ~renderer ~extra m
   | `Asset _ -> Ok [] (* TODO *)
 
@@ -114,6 +96,43 @@ 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 _ -> (
+      match Fs.File.read source_file with
+      | Error (`Msg msg) ->
+          Error (`Msg (Format.sprintf "Couldn't load source file: %s" msg))
+      | Ok source_code ->
+          let syntax_info =
+            Syntax_highlighter.syntax_highlighting_locs source_code
+          in
+          let rendered =
+            Odoc_document.Renderer.documents_of_implementation ~syntax impl
+              syntax_info source_code
+          in
+          Ok rendered)
+  | _, 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 =
+  Odoc_file.load file >>= fun unit ->
+  match unit.content with
+  | Odoc_file.Impl_content impl ->
+      documents_of_implementation ~warnings_options ~syntax impl source_file
+      >>= fun docs ->
+      List.iter
+        (render_document renderer ~output ~sidebar:None ~extra_suffix ~extra)
+        docs;
+      Ok ()
+  | Page_content _ | Unit_content _ | Asset_content _ ->
+      Error (`Msg "Expected an implementation unit")
+
 let targets_odoc ~resolver ~warnings_options ~syntax ~renderer ~output:root_dir
     ~extra odoctree =
   let docs =

src/odoc/rendering.mli

@@ -22,6 +22,17 @@ val generate_odoc :
   Fpath.t ->
   (unit, [> msg ]) result
 
+val generate_impl_odoc :
+  syntax:Renderer.syntax ->
+  warnings_options:Odoc_model.Error.warnings_options ->
+  renderer:'a Renderer.t ->
+  output:Fs.directory ->
+  source_file:Fpath.t option ->
+  extra_suffix:string option ->
+  'a ->
+  Fpath.t ->
+  (unit, [> msg ]) result
+
 val targets_odoc :
   resolver:Resolver.t ->
   warnings_options:Odoc_model.Error.warnings_options ->

test/integration/json_expansion_with_sources.t/run.t

@@ -24,17 +24,29 @@ Test the JSON output in the presence of expanded modules.
   html/Main/A/index.html.json
   html/Main/A/B/index.html.json
   $ odoc html-targets --source a.ml -o html impl-main__A.odocl
-  html/src/a.ml.html
+  odoc: unknown option '--source'.
+  Usage: odoc html-targets [OPTION]… FILE.odocl
+  Try 'odoc html-targets --help' or 'odoc --help' for more information.
+  [2]
   $ odoc html-targets --source main.ml -o html impl-main.odocl
-  html/src/main.ml.html
+  odoc: unknown option '--source'.
+  Usage: odoc html-targets [OPTION]… FILE.odocl
+  Try 'odoc html-targets --help' or 'odoc --help' for more information.
+  [2]
   $ odoc html-targets --source a.ml --as-json -o html impl-main__A.odocl
-  html/src/a.ml.html.json
+  odoc: unknown option '--source'.
+  Usage: odoc html-targets [OPTION]… FILE.odocl
+  Try 'odoc html-targets --help' or 'odoc --help' for more information.
+  [2]
   $ odoc html-targets --source main.ml --as-json -o html impl-main.odocl
-  html/src/main.ml.html.json
+  odoc: unknown option '--source'.
+  Usage: odoc html-targets [OPTION]… FILE.odocl
+  Try 'odoc html-targets --help' or 'odoc --help' for more information.
+  [2]
 
-  $ odoc html-generate --source a.ml --as-json -o html impl-main__A.odocl
+  $ odoc html-generate-impl --source a.ml --as-json -o html impl-main__A.odocl
   $ odoc html-generate --as-json -o html main__A.odocl
-  $ odoc html-generate --source main.ml --as-json -o html impl-main.odocl
+  $ odoc html-generate-impl --source main.ml --as-json -o html impl-main.odocl
   $ odoc html-generate --as-json -o html main.odocl
 
   $ cat html/Main/index.html.json

test/odoc_print/odoc_print.ml

@@ -222,9 +222,6 @@ let run inp short long_paths show_canonical show_expansions
   in
   Odoc_file.load inp >>= fun unit ->
   match unit.content with
-  | Odoc_file.Source_tree_content tree ->
-      print_json_desc Lang_desc.source_tree_page_t tree;
-      Ok ()
   | Odoc_file.Page_content page ->
       print_json_desc Lang_desc.page_t page;
       Ok ()

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 --source main.ml --indent -o html impl-main.odocl
-  $ odoc html-generate --source a.ml --indent -o html impl-main__A.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
 
 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 --source s.ml --indent -o html impl-s.odocl
+  $ odoc html-generate-impl --source s.ml --indent -o html impl-s.odocl
   $ odoc html-generate --indent -o html s.odocl
-  $ odoc html-generate --source a.ml --indent -o html impl-a.odocl
+  $ odoc html-generate-impl --source a.ml --indent -o html impl-a.odocl
   $ odoc html-generate --indent -o html a.odocl
-  $ odoc html-generate --source b.ml --indent -o html impl-b.odocl
+  $ odoc html-generate-impl --source b.ml --indent -o html impl-b.odocl
   $ 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 --source main.ml --indent -o html impl-main.odocl
+  $ odoc html-generate-impl --source main.ml --indent -o html impl-main.odocl
   $ odoc html-generate --indent -o html main.odocl
-  $ odoc html-generate --source a.ml --hidden --indent -o html impl-main__A.odocl
+  $ odoc html-generate-impl --source a.ml --hidden --indent -o html impl-main__A.odocl
   $ 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 --source main.ml --indent -o html impl-main.odocl
+  $ odoc html-generate-impl --source main.ml --indent -o html impl-main.odocl
   $ odoc html-generate --indent -o html main.odocl
-  $ odoc html-generate --source a.ml --indent -o html impl-main__A.odocl
+  $ odoc html-generate-impl --source a.ml --indent -o html impl-main__A.odocl
   $ odoc html-generate --hidden --indent -o html main__A.odocl
-  $ odoc html-generate --source b.ml --indent -o html impl-main__B.odocl
+  $ odoc html-generate-impl --source b.ml --indent -o html impl-main__B.odocl
   $ 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

@@ -6,7 +6,7 @@ Checking that source links exists inside recursive modules.
   $ odoc link -I . impl-main.odoc
   $ odoc link -I . main.odoc
   $ odoc html-generate --indent -o html main.odocl
-  $ odoc html-generate --source main.ml --indent -o html impl-main.odocl
+  $ odoc html-generate-impl --source main.ml --indent -o html impl-main.odocl
 
 Both modules should contain source links