From 437b48a6af980a8194491f8d271a8274c12f5343 Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Fri, 21 Oct 2022 17:51:18 +0200 Subject: [PATCH 1/3] Manpage: Group commands into sections The sections allow to quickly find the important commands. The "Legacy pipeline" section give less importances to the no longer recommended commands. --- src/odoc/bin/main.ml | 75 ++++++++++++++++++++++++++++++++------------ 1 file changed, 55 insertions(+), 20 deletions(-) diff --git a/src/odoc/bin/main.ml b/src/odoc/bin/main.ml index e237e95ae5..df25469205 100644 --- a/src/odoc/bin/main.ml +++ b/src/odoc/bin/main.ml @@ -111,6 +111,22 @@ let open_modules = let default = [ "Stdlib" ] in Arg.(value & opt_all string default & info ~docv:"MODULE" ~doc [ "open" ]) +let section_pipeline = "COMMANDS: Compilation pipeline" +let section_generators = "COMMANDS: Alternative generators" +let section_support = "COMMANDS: Scripting" +let section_legacy = "COMMANDS: Legacy pipeline" +let section_deprecated = "COMMANDS: Deprecated" + +(** Sections in the order they should appear. *) +let sections = + [ + section_pipeline; + section_generators; + section_support; + section_legacy; + section_deprecated; + ] + module Compile : sig val output_file : dst:string option -> input:Fs.file -> Fs.file @@ -224,7 +240,7 @@ end = struct $ warnings_options)) let info = - Term.info "compile" + Term.info "compile" ~docs:section_pipeline ~doc:"Compile a cmti, cmt, cmi or mld file to an odoc file." end @@ -243,7 +259,7 @@ module Support_files_command = struct "Copy the support files (e.g. default theme, JavaScript files) to the \ output directory." in - Term.info ~doc "support-files" + Term.info ~docs:section_pipeline ~doc "support-files" end module Css = struct @@ -254,7 +270,7 @@ module Css = struct "DEPRECATED: Use `odoc support-files' to copy the CSS file for the \ default theme." in - Term.info ~doc "css" + Term.info ~docs:section_deprecated ~doc "css" end module Odoc_link : sig @@ -295,7 +311,8 @@ end = struct $ (const link $ odoc_file_directories $ input $ dst $ warnings_options $ open_modules)) - let info = Term.info ~doc:"Link odoc files together" "link" + let info = + Term.info ~docs:section_pipeline ~doc:"Link odoc files together" "link" end module type S = sig @@ -304,6 +321,8 @@ module type S = sig val renderer : args Odoc_document.Renderer.t val extra_args : args Cmdliner.Term.t + + val generate_docs : string end module Make_renderer (R : S) : sig @@ -345,7 +364,7 @@ end = struct let doc = Format.sprintf "Render %s files from an odoc one" R.renderer.name in - Term.info ~doc R.renderer.name + Term.info ~docs:section_legacy ~doc R.renderer.name end let process = Process.(cmd, info) @@ -375,7 +394,7 @@ end = struct let doc = Format.sprintf "Generate %s files from an odocl one" R.renderer.name in - Term.info ~doc (R.renderer.name ^ "-generate") + Term.info ~docs:R.generate_docs ~doc (R.renderer.name ^ "-generate") end let generate = Generate.(cmd, info) @@ -407,7 +426,10 @@ end = struct const handle_error $ (const list_targets $ dst () $ back_compat $ R.extra_args $ input)) - let info = Term.info (R.renderer.name ^ "-targets") ~doc:"TODO: Fill in." + let info = + Term.info + (R.renderer.name ^ "-targets") + ~docs:section_support ~doc:"TODO: Fill in." end let targets = Targets.(cmd, info) @@ -430,8 +452,8 @@ end = struct $ (const reference_to_url $ odoc_file_directories $ reference)) let info = - Term.info ~doc:"Resolve a reference and output its corresponding url" - "latex-url" + Term.info ~docs:section_support + ~doc:"Resolve a reference and output its corresponding url" "latex-url" end module Odoc_html_args = struct @@ -534,6 +556,8 @@ module Odoc_html_args = struct Term.( const config $ semantic_uris $ closed_details $ indent $ theme_uri $ support_uri $ flat $ as_json) + + let generate_docs = section_pipeline end module Odoc_html = Make_renderer (Odoc_html_args) @@ -563,8 +587,8 @@ end = struct $ odoc_file_directories $ reference)) let info = - Term.info ~doc:"Resolve a reference and output its corresponding url" - "html-url" + Term.info ~docs:section_support + ~doc:"Resolve a reference and output its corresponding url" "html-url" end module Html_fragment : sig @@ -612,8 +636,8 @@ end = struct $ input $ warnings_options)) let info = - Term.info ~doc:"Generates an html fragment file from an mld one" - "html-fragment" + Term.info ~docs:section_legacy + ~doc:"Generates an html fragment file from an mld one" "html-fragment" end module Odoc_manpage = Make_renderer (struct @@ -622,6 +646,8 @@ module Odoc_manpage = Make_renderer (struct let renderer = Man_page.renderer let extra_args = Term.const () + + let generate_docs = section_generators end) module Odoc_latex = Make_renderer (struct @@ -636,6 +662,8 @@ module Odoc_latex = Make_renderer (struct let extra_args = let f with_children = { Latex.with_children } in Term.(const f $ with_children) + + let generate_docs = section_generators end) module Depends = struct @@ -660,7 +688,7 @@ module Depends = struct Term.(const list_dependencies $ input) let info = - Term.info "compile-deps" + Term.info "compile-deps" ~docs:section_legacy ~doc: "List units (with their digest) which needs to be compiled in order \ to compile this one. The unit itself and its digest is also \ @@ -706,7 +734,7 @@ module Depends = struct Term.(const handle_error $ (const list_dependencies $ input)) let info = - Term.info "link-deps" + Term.info "link-deps" ~docs:section_legacy ~doc: "lists the packages which need to be in odoc's load path to link the \ .odoc files in the given directory" @@ -728,7 +756,9 @@ module Depends = struct let cmd _ = Link.list_dependencies in Term.(const handle_error $ (const cmd $ includes $ input)) - let info = Term.info "html-deps" ~doc:"DEPRECATED: alias for link-deps" + let info = + Term.info "html-deps" ~docs:section_deprecated + ~doc:"DEPRECATED: alias for link-deps" end end @@ -742,7 +772,8 @@ module Targets = struct let cmd = Term.(const list_targets $ Compile.dst $ Compile.input) - let info = Term.info "compile-targets" ~doc:"TODO: Fill in." + let info = + Term.info "compile-targets" ~docs:section_legacy ~doc:"TODO: Fill in." end module Support_files = struct @@ -753,7 +784,7 @@ module Targets = struct Term.(const list_targets $ Support_files_command.without_theme $ dst ()) let info = - Term.info "support-files-targets" + Term.info "support-files-targets" ~docs:section_support ~doc:"Lists the names of the files that 'odoc support-files' outputs." end end @@ -774,7 +805,7 @@ module Odoc_error = struct let cmd = Term.(const handle_error $ (const errors $ input)) let info = - Term.info "errors" + Term.info "errors" ~docs:section_support ~doc:"Print errors that occurred while an .odoc file was generated." end @@ -815,8 +846,12 @@ let () = "Available subcommands: %s\nSee --help for more information.\n%!" (String.concat ~sep:", " available_subcommands) in + let man = + (* Show sections in a defined order. *) + List.map ~f:(fun s -> `S s) sections + in ( Term.(const print_default $ const ()), - Term.info ~version:"%%VERSION%%" "odoc" ) + Term.info ~man ~version:"%%VERSION%%" "odoc" ) in match Term.eval_choice ~err:Format.err_formatter default subcommands with | `Error _ -> From 97f8fa5f63488af2104b89688c50b4e7be24ca37 Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Fri, 21 Oct 2022 19:24:10 +0200 Subject: [PATCH 2/3] Improve the manpage for various subcommands Document the dependencies in the compile and link steps. Fill the missing documentation. Improve consistency and formatting. --- src/odoc/bin/main.ml | 158 ++++++++++++++++++++++++++++--------------- 1 file changed, 104 insertions(+), 54 deletions(-) diff --git a/src/odoc/bin/main.ml b/src/odoc/bin/main.ml index df25469205..f4b9bf202a 100644 --- a/src/odoc/bin/main.ml +++ b/src/odoc/bin/main.ml @@ -42,7 +42,7 @@ let docs = "ARGUMENTS" let odoc_file_directories = let doc = - "Where to look for required .odoc files. (Can be present several times)." + "Where to look for required $(i,.odoc) files. Can be present several times." in Arg.( value @@ -118,7 +118,7 @@ let section_legacy = "COMMANDS: Legacy pipeline" let section_deprecated = "COMMANDS: Deprecated" (** Sections in the order they should appear. *) -let sections = +let main_page_sections = [ section_pipeline; section_generators; @@ -189,26 +189,23 @@ end = struct ~warnings_options input let input = - let doc = "Input cmti, cmt, cmi or mld file" in + let doc = "Input $(i,.cmti), $(i,.cmt), $(i,.cmi) or $(i,.mld) file." in Arg.(required & pos 0 (some file) None & info ~doc ~docv:"FILE" []) let dst = let doc = - "Output file path. Non-existing intermediate directories are\n\ - \ created. If absent outputs a $(i,BASE).odoc file in \ - the same\n\ - \ directory as the input file where $(i,BASE) is the \ - basename\n\ - \ of the input file (for mld files the \"page-\" prefix \ - will be\n\ - \ added if not already present in the input basename)." + "Output file path. Non-existing intermediate directories are created. If \ + absent outputs a $(i,BASE.odoc) file in the same directory as the input \ + file where $(i,BASE) is the basename of the input file. For mld files \ + the \"page-\" prefix will be added if not already present in the input \ + basename." in Arg.(value & opt (some string) None & info ~docs ~docv:"PATH" ~doc [ "o" ]) let children = let doc = - "Specify the odoc file as a child. Can be used multiple times. Only \ - applies to mld files" + "Specify the $(i,.odoc) file as a child. Can be used multiple times. \ + Only applies to mld files" in let default = [] in Arg.( @@ -216,21 +213,23 @@ end = struct let cmd = let package_opt = - let doc = "Package the input is part of (deprecated - use '--parent')" in + let doc = + "Package the input is part of. Deprecated: use '--parent' instead." + in Arg.( value & opt (some string) None & info ~docs ~docv:"PKG" ~doc [ "package"; "pkg" ]) in let parent_opt = - let doc = "Parent page or subpage" in + let doc = "Parent page or subpage." in Arg.( value & opt (some string) None & info ~docs ~docv:"PARENT" ~doc [ "parent" ]) in let resolve_fwd_refs = - let doc = "Try resolving forward references" in + let doc = "Try resolving forward references." in Arg.(value & flag & info ~doc [ "r"; "resolve-fwd-refs" ]) in Term.( @@ -240,8 +239,20 @@ end = struct $ warnings_options)) let info = - Term.info "compile" ~docs:section_pipeline - ~doc:"Compile a cmti, cmt, cmi or mld file to an odoc file." + let man = + [ + `S "DEPENDENCIES"; + `P + "Dependencies between compilation units is the same as while \ + compiling the initial OCaml modules."; + `P "Mld pages don't have any dependency."; + ] + in + let doc = + "Compile a $(i,.cmti), $(i,.cmt), $(i,.cmi) or $(i,.mld) file to an \ + $(i,.odoc) file." + in + Term.info "compile" ~docs:section_pipeline ~doc ~man end module Support_files_command = struct @@ -267,7 +278,7 @@ module Css = struct let info = let doc = - "DEPRECATED: Use `odoc support-files' to copy the CSS file for the \ + "DEPRECATED: Use $(i,odoc support-files) to copy the CSS file for the \ default theme." in Term.info ~docs:section_deprecated ~doc "css" @@ -295,16 +306,19 @@ end = struct let dst = let doc = - "Output file path. Non-existing intermediate directories are\n\ - \ created. If absent outputs a .odocl file in the same\n\ - \ directory as the input file." + "Output file path. Non-existing intermediate directories are created. If \ + absent outputs a $(i,.odocl) file in the same directory as the input \ + file with the same basename." in - Arg.(value & opt (some string) None & info ~docs ~docv:"PATH" ~doc [ "o" ]) + Arg.( + value + & opt (some string) None + & info ~docs ~docv:"PATH.odocl" ~doc [ "o" ]) let cmd = let input = let doc = "Input file" in - Arg.(required & pos 0 (some file) None & info ~doc ~docv:"file.odoc" []) + Arg.(required & pos 0 (some file) None & info ~doc ~docv:"FILE.odoc" []) in Term.( const handle_error @@ -312,7 +326,21 @@ end = struct $ open_modules)) let info = - Term.info ~docs:section_pipeline ~doc:"Link odoc files together" "link" + let man = + [ + `S "DEPENDENCIES"; + `P + "Any link step depends on the result of all the compile results that \ + could potentially be needed to resolve forward references. A \ + correct approximation is to start linking only after every compile \ + steps are done, passing everything that's possible to $(i,-I). Link \ + steps don't have dependencies between them."; + ] + in + let doc = + "Second stage of compilation. Link a $(i,.odoc) into a $(i,.odocl)." + in + Term.info ~docs:section_pipeline ~doc ~man "link" end module type S = sig @@ -332,9 +360,13 @@ module Make_renderer (R : S) : sig val generate : unit Term.t * Term.info end = struct - let input = - let doc = "Input file" in - Arg.(required & pos 0 (some file) None & info ~doc ~docv:"file.odoc" []) + let input_odoc = + let doc = "Input file." in + Arg.(required & pos 0 (some file) None & info ~doc ~docv:"FILE.odoc" []) + + let input_odocl = + let doc = "Input file." in + Arg.(required & pos 0 (some file) None & info ~doc ~docv:"FILE.odocl" []) module Process = struct let process extra _hidden directories output_dir syntax input_file @@ -358,11 +390,14 @@ end = struct Term.( const handle_error $ (const process $ R.extra_args $ hidden $ odoc_file_directories - $ dst ~create:true () $ syntax $ input $ warnings_options)) + $ dst ~create:true () $ syntax $ input_odoc $ warnings_options)) let info = let doc = - Format.sprintf "Render %s files from an odoc one" R.renderer.name + Format.sprintf + "Render %s files from a $(i,.odoc). $(i,link) then $(i,%s-generate) \ + should be used instead." + R.renderer.name R.renderer.name in Term.info ~docs:section_legacy ~doc R.renderer.name end @@ -388,11 +423,11 @@ end = struct Term.( const handle_error $ (const generate $ R.extra_args $ hidden $ dst ~create:true () $ syntax - $ extra_suffix $ input)) + $ extra_suffix $ input_odocl)) let info = let doc = - Format.sprintf "Generate %s files from an odocl one" R.renderer.name + Format.sprintf "Generate %s files from a $(i,.odocl)." R.renderer.name in Term.info ~docs:R.generate_docs ~doc (R.renderer.name ^ "-generate") end @@ -413,8 +448,8 @@ end = struct let back_compat = let doc = - "For backwards compatibility when processing odoc rather than odocl \ - files." + "For backwards compatibility when processing $(i,.odoc) rather than \ + $(i,.odocl) files." in Arg.( value @@ -424,12 +459,17 @@ end = struct let cmd = Term.( const handle_error - $ (const list_targets $ dst () $ back_compat $ R.extra_args $ input)) + $ (const list_targets $ dst () $ back_compat $ R.extra_args + $ input_odocl)) let info = - Term.info - (R.renderer.name ^ "-targets") - ~docs:section_support ~doc:"TODO: Fill in." + let doc = + Format.sprintf + "Print the files that would be generated by $(i,%s-generate). Works \ + on both $(i,.odoc) and $(i,.odocl) files." + R.renderer.name + in + Term.info (R.renderer.name ^ "-targets") ~docs:section_support ~doc end let targets = Targets.(cmd, info) @@ -453,7 +493,7 @@ end = struct let info = Term.info ~docs:section_support - ~doc:"Resolve a reference and output its corresponding url" "latex-url" + ~doc:"Resolve a reference and output its corresponding url." "latex-url" end module Odoc_html_args = struct @@ -462,7 +502,7 @@ module Odoc_html_args = struct let renderer = Html_page.renderer let semantic_uris = - let doc = "Generate pretty (semantic) links" in + let doc = "Generate pretty (semantic) links." in Arg.(value & flag (info ~doc [ "semantic-uris"; "pretty-uris" ])) let closed_details = @@ -473,7 +513,7 @@ module Odoc_html_args = struct Arg.(value & flag (info ~doc [ "closed-details" ])) let indent = - let doc = "Format the output HTML files with indentation" in + let doc = "Format the output HTML files with indentation." in Arg.(value & flag (info ~doc [ "indent" ])) (* Very basic validation and normalization for URI paths. *) @@ -588,7 +628,7 @@ end = struct let info = Term.info ~docs:section_support - ~doc:"Resolve a reference and output its corresponding url" "html-url" + ~doc:"Resolve a reference and output its corresponding url." "html-url" end module Html_fragment : sig @@ -614,13 +654,13 @@ end = struct let cmd = let output = - let doc = "Output HTML fragment file" in + let doc = "Output HTML fragment file." in Arg.( value & opt string "/dev/stdout" & info ~docs ~docv:"file.html" ~doc [ "o"; "output-file" ]) in let input = - let doc = "Input documentation page file" in + let doc = "Input documentation page file." in Arg.(required & pos 0 (some file) None & info ~doc ~docv:"file.mld" []) in let xref_base_uri = @@ -637,7 +677,7 @@ end = struct let info = Term.info ~docs:section_legacy - ~doc:"Generates an html fragment file from an mld one" "html-fragment" + ~doc:"Generates an html fragment file from an mld one." "html-fragment" end module Odoc_manpage = Make_renderer (struct @@ -656,7 +696,7 @@ module Odoc_latex = Make_renderer (struct let renderer = Latex.renderer let with_children = - let doc = "Include children at the end of the page" in + let doc = "Include children at the end of the page." in Arg.(value & opt bool true & info ~docv:"BOOL" ~doc [ "with-children" ]) let extra_args = @@ -692,7 +732,9 @@ module Depends = struct ~doc: "List units (with their digest) which needs to be compiled in order \ to compile this one. The unit itself and its digest is also \ - reported in the output." + reported in the output.\n\ + Dependencies between compile steps are the same as when compiling \ + the ocaml modules." end module Link = struct @@ -736,8 +778,12 @@ module Depends = struct let info = Term.info "link-deps" ~docs:section_legacy ~doc: - "lists the packages which need to be in odoc's load path to link the \ - .odoc files in the given directory" + "Lists the packages which need to be in odoc's load path to link the \ + $(i,.odoc) files in the given directory.\n\ + The result is not correct in case of forward references. A \ + conservative approximation is: any link step depends on the result \ + of all the compile steps that could be targeted by a forward \ + reference." end module Odoc_html = struct @@ -773,7 +819,10 @@ module Targets = struct let cmd = Term.(const list_targets $ Compile.dst $ Compile.input) let info = - Term.info "compile-targets" ~docs:section_legacy ~doc:"TODO: Fill in." + Term.info "compile-targets" ~docs:section_legacy + ~doc: + "Print the name of the file produced by $(i,compile). If $(i,-o) is \ + passed, the same path is printed but error checking is performed." end module Support_files = struct @@ -785,7 +834,8 @@ module Targets = struct let info = Term.info "support-files-targets" ~docs:section_support - ~doc:"Lists the names of the files that 'odoc support-files' outputs." + ~doc: + "Lists the names of the files that $(i,odoc support-files) outputs." end end @@ -799,14 +849,14 @@ module Odoc_error = struct Ok () let input = - let doc = "Input odoc or odocl file" in + let doc = "Input $(i,.odoc) or $(i,.odocl) file" in Arg.(required & pos 0 (some file) None & info ~doc ~docv:"FILE" []) let cmd = Term.(const handle_error $ (const errors $ input)) let info = Term.info "errors" ~docs:section_support - ~doc:"Print errors that occurred while an .odoc file was generated." + ~doc:"Print errors that occurred while compiling or linking." end let () = @@ -848,7 +898,7 @@ let () = in let man = (* Show sections in a defined order. *) - List.map ~f:(fun s -> `S s) sections + List.map ~f:(fun s -> `S s) main_page_sections in ( Term.(const print_default $ const ()), Term.info ~man ~version:"%%VERSION%%" "odoc" ) From 55c410bc272499d1c35ff6aae6abe59965112dec Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Mon, 24 Oct 2022 10:04:50 +0200 Subject: [PATCH 3/3] Sort subcommands by section Sections are assigned while defining the list to make sure they are still in sync. --- src/odoc/bin/main.ml | 190 ++++++++++++++++++++----------------------- 1 file changed, 89 insertions(+), 101 deletions(-) diff --git a/src/odoc/bin/main.ml b/src/odoc/bin/main.ml index f4b9bf202a..874ffe09a4 100644 --- a/src/odoc/bin/main.ml +++ b/src/odoc/bin/main.ml @@ -111,22 +111,6 @@ let open_modules = let default = [ "Stdlib" ] in Arg.(value & opt_all string default & info ~docv:"MODULE" ~doc [ "open" ]) -let section_pipeline = "COMMANDS: Compilation pipeline" -let section_generators = "COMMANDS: Alternative generators" -let section_support = "COMMANDS: Scripting" -let section_legacy = "COMMANDS: Legacy pipeline" -let section_deprecated = "COMMANDS: Deprecated" - -(** Sections in the order they should appear. *) -let main_page_sections = - [ - section_pipeline; - section_generators; - section_support; - section_legacy; - section_deprecated; - ] - module Compile : sig val output_file : dst:string option -> input:Fs.file -> Fs.file @@ -136,7 +120,7 @@ module Compile : sig val cmd : unit Term.t - val info : Term.info + val info : docs:string -> Term.info end = struct let has_page_prefix file = file |> Fs.File.basename |> Fs.File.to_string @@ -238,7 +222,7 @@ end = struct $ package_opt $ parent_opt $ open_modules $ children $ input $ warnings_options)) - let info = + let info ~docs = let man = [ `S "DEPENDENCIES"; @@ -252,7 +236,7 @@ end = struct "Compile a $(i,.cmti), $(i,.cmt), $(i,.cmi) or $(i,.mld) file to an \ $(i,.odoc) file." in - Term.info "compile" ~docs:section_pipeline ~doc ~man + Term.info "compile" ~docs ~doc ~man end module Support_files_command = struct @@ -265,29 +249,29 @@ module Support_files_command = struct let cmd = Term.(const support_files $ without_theme $ dst ~create:true ()) - let info = + let info ~docs = let doc = "Copy the support files (e.g. default theme, JavaScript files) to the \ output directory." in - Term.info ~docs:section_pipeline ~doc "support-files" + Term.info ~docs ~doc "support-files" end module Css = struct let cmd = Support_files_command.cmd - let info = + let info ~docs = let doc = "DEPRECATED: Use $(i,odoc support-files) to copy the CSS file for the \ default theme." in - Term.info ~docs:section_deprecated ~doc "css" + Term.info ~docs ~doc "css" end module Odoc_link : sig val cmd : unit Term.t - val info : Term.info + val info : docs:string -> Term.info end = struct let get_output_file ~output_file ~input = match output_file with @@ -325,7 +309,7 @@ end = struct $ (const link $ odoc_file_directories $ input $ dst $ warnings_options $ open_modules)) - let info = + let info ~docs = let man = [ `S "DEPENDENCIES"; @@ -340,7 +324,7 @@ end = struct let doc = "Second stage of compilation. Link a $(i,.odoc) into a $(i,.odocl)." in - Term.info ~docs:section_pipeline ~doc ~man "link" + Term.info ~docs ~doc ~man "link" end module type S = sig @@ -349,16 +333,14 @@ module type S = sig val renderer : args Odoc_document.Renderer.t val extra_args : args Cmdliner.Term.t - - val generate_docs : string end module Make_renderer (R : S) : sig - val process : unit Term.t * Term.info + val process : docs:string -> unit Term.t * Term.info - val targets : unit Term.t * Term.info + val targets : docs:string -> unit Term.t * Term.info - val generate : unit Term.t * Term.info + val generate : docs:string -> unit Term.t * Term.info end = struct let input_odoc = let doc = "Input file." in @@ -392,17 +374,17 @@ end = struct $ (const process $ R.extra_args $ hidden $ odoc_file_directories $ dst ~create:true () $ syntax $ input_odoc $ warnings_options)) - let info = + let info ~docs = let doc = Format.sprintf "Render %s files from a $(i,.odoc). $(i,link) then $(i,%s-generate) \ should be used instead." R.renderer.name R.renderer.name in - Term.info ~docs:section_legacy ~doc R.renderer.name + Term.info ~docs ~doc R.renderer.name end - let process = Process.(cmd, info) + let process ~docs = Process.(cmd, info ~docs) module Generate = struct let generate extra _hidden output_dir syntax extra_suffix input_file = @@ -425,14 +407,14 @@ end = struct $ (const generate $ R.extra_args $ hidden $ dst ~create:true () $ syntax $ extra_suffix $ input_odocl)) - let info = + let info ~docs = let doc = Format.sprintf "Generate %s files from a $(i,.odocl)." R.renderer.name in - Term.info ~docs:R.generate_docs ~doc (R.renderer.name ^ "-generate") + Term.info ~docs ~doc (R.renderer.name ^ "-generate") end - let generate = Generate.(cmd, info) + let generate ~docs = Generate.(cmd, info ~docs) module Targets = struct let list_targets output_dir directories extra odoc_file = @@ -462,23 +444,22 @@ end = struct $ (const list_targets $ dst () $ back_compat $ R.extra_args $ input_odocl)) - let info = + let info ~docs = let doc = Format.sprintf - "Print the files that would be generated by $(i,%s-generate). Works \ - on both $(i,.odoc) and $(i,.odocl) files." + "Print the files that would be generated by $(i,%s-generate)." R.renderer.name in - Term.info (R.renderer.name ^ "-targets") ~docs:section_support ~doc + Term.info (R.renderer.name ^ "-targets") ~docs ~doc end - let targets = Targets.(cmd, info) + let targets ~docs = Targets.(cmd, info ~docs) end module Odoc_latex_url : sig val cmd : unit Term.t - val info : Term.info + val info : docs:string -> Term.info end = struct let reference = let doc = "The reference to be resolved and whose url to be generated." in @@ -491,9 +472,9 @@ end = struct const handle_error $ (const reference_to_url $ odoc_file_directories $ reference)) - let info = - Term.info ~docs:section_support - ~doc:"Resolve a reference and output its corresponding url." "latex-url" + let info ~docs = + Term.info ~docs ~doc:"Resolve a reference and output its corresponding url." + "latex-url" end module Odoc_html_args = struct @@ -596,8 +577,6 @@ module Odoc_html_args = struct Term.( const config $ semantic_uris $ closed_details $ indent $ theme_uri $ support_uri $ flat $ as_json) - - let generate_docs = section_pipeline end module Odoc_html = Make_renderer (Odoc_html_args) @@ -605,7 +584,7 @@ module Odoc_html = Make_renderer (Odoc_html_args) module Odoc_html_url : sig val cmd : unit Term.t - val info : Term.info + val info : docs:string -> Term.info end = struct let root_url = let doc = @@ -626,15 +605,15 @@ end = struct $ (const reference_to_url $ Odoc_html_args.extra_args $ root_url $ odoc_file_directories $ reference)) - let info = - Term.info ~docs:section_support - ~doc:"Resolve a reference and output its corresponding url." "html-url" + let info ~docs = + Term.info ~docs ~doc:"Resolve a reference and output its corresponding url." + "html-url" end module Html_fragment : sig val cmd : unit Term.t - val info : Term.info + val info : docs:string -> Term.info end = struct let html_fragment directories xref_base_uri output_file input_file warnings_options = @@ -675,9 +654,9 @@ end = struct $ (const html_fragment $ odoc_file_directories $ xref_base_uri $ output $ input $ warnings_options)) - let info = - Term.info ~docs:section_legacy - ~doc:"Generates an html fragment file from an mld one." "html-fragment" + let info ~docs = + Term.info ~docs ~doc:"Generates an html fragment file from an mld one." + "html-fragment" end module Odoc_manpage = Make_renderer (struct @@ -686,8 +665,6 @@ module Odoc_manpage = Make_renderer (struct let renderer = Man_page.renderer let extra_args = Term.const () - - let generate_docs = section_generators end) module Odoc_latex = Make_renderer (struct @@ -702,8 +679,6 @@ module Odoc_latex = Make_renderer (struct let extra_args = let f with_children = { Latex.with_children } in Term.(const f $ with_children) - - let generate_docs = section_generators end) module Depends = struct @@ -727,8 +702,8 @@ module Depends = struct in Term.(const list_dependencies $ input) - let info = - Term.info "compile-deps" ~docs:section_legacy + let info ~docs = + Term.info "compile-deps" ~docs ~doc: "List units (with their digest) which needs to be compiled in order \ to compile this one. The unit itself and its digest is also \ @@ -775,15 +750,13 @@ module Depends = struct in Term.(const handle_error $ (const list_dependencies $ input)) - let info = - Term.info "link-deps" ~docs:section_legacy + let info ~docs = + Term.info "link-deps" ~docs ~doc: - "Lists the packages which need to be in odoc's load path to link the \ - $(i,.odoc) files in the given directory.\n\ - The result is not correct in case of forward references. A \ - conservative approximation is: any link step depends on the result \ - of all the compile steps that could be targeted by a forward \ - reference." + "Lists a subset of the packages and modules which need to be in \ + odoc's load path to link the $(i, odoc) files in the given \ + directory. Additional packages may be required to resolve all \ + references." end module Odoc_html = struct @@ -802,9 +775,8 @@ module Depends = struct let cmd _ = Link.list_dependencies in Term.(const handle_error $ (const cmd $ includes $ input)) - let info = - Term.info "html-deps" ~docs:section_deprecated - ~doc:"DEPRECATED: alias for link-deps" + let info ~docs = + Term.info "html-deps" ~docs ~doc:"DEPRECATED: alias for link-deps" end end @@ -818,8 +790,8 @@ module Targets = struct let cmd = Term.(const list_targets $ Compile.dst $ Compile.input) - let info = - Term.info "compile-targets" ~docs:section_legacy + let info ~docs = + Term.info "compile-targets" ~docs ~doc: "Print the name of the file produced by $(i,compile). If $(i,-o) is \ passed, the same path is printed but error checking is performed." @@ -832,8 +804,8 @@ module Targets = struct let cmd = Term.(const list_targets $ Support_files_command.without_theme $ dst ()) - let info = - Term.info "support-files-targets" ~docs:section_support + let info ~docs = + Term.info "support-files-targets" ~docs ~doc: "Lists the names of the files that $(i,odoc support-files) outputs." end @@ -854,37 +826,53 @@ module Odoc_error = struct let cmd = Term.(const handle_error $ (const errors $ input)) - let info = - Term.info "errors" ~docs:section_support + let info ~docs = + Term.info "errors" ~docs ~doc:"Print errors that occurred while compiling or linking." end +let section_pipeline = "COMMANDS: Compilation pipeline" +let section_generators = "COMMANDS: Alternative generators" +let section_support = "COMMANDS: Scripting" +let section_legacy = "COMMANDS: Legacy pipeline" +let section_deprecated = "COMMANDS: Deprecated" + +(** Sections in the order they should appear. *) +let main_page_sections = + [ + section_pipeline; + section_generators; + section_support; + section_legacy; + section_deprecated; + ] + let () = Printexc.record_backtrace true; let subcommands = [ - Compile.(cmd, info); - Odoc_html.process; - Odoc_html.targets; - Odoc_html.generate; - Odoc_manpage.process; - Odoc_manpage.targets; - Odoc_manpage.generate; - Odoc_latex.process; - Odoc_latex.targets; - Odoc_latex.generate; - Html_fragment.(cmd, info); - Support_files_command.(cmd, info); - Css.(cmd, info); - Depends.Compile.(cmd, info); - Depends.Link.(cmd, info); - Depends.Odoc_html.(cmd, info); - Targets.Compile.(cmd, info); - Targets.Support_files.(cmd, info); - Odoc_link.(cmd, info); - Odoc_error.(cmd, info); - Odoc_html_url.(cmd, info); - Odoc_latex_url.(cmd, info); + Compile.(cmd, info ~docs:section_pipeline); + Odoc_link.(cmd, info ~docs:section_pipeline); + Odoc_html.generate ~docs:section_pipeline; + Support_files_command.(cmd, info ~docs:section_pipeline); + Odoc_manpage.generate ~docs:section_generators; + Odoc_latex.generate ~docs:section_generators; + Odoc_html_url.(cmd, info ~docs:section_support); + Odoc_latex_url.(cmd, info ~docs:section_support); + Targets.Support_files.(cmd, info ~docs:section_support); + Odoc_error.(cmd, info ~docs:section_support); + Odoc_html.targets ~docs:section_support; + Odoc_manpage.targets ~docs:section_support; + Odoc_latex.targets ~docs:section_support; + Depends.Compile.(cmd, info ~docs:section_support); + Targets.Compile.(cmd, info ~docs:section_support); + Html_fragment.(cmd, info ~docs:section_legacy); + Odoc_html.process ~docs:section_legacy; + Odoc_manpage.process ~docs:section_legacy; + Odoc_latex.process ~docs:section_legacy; + Depends.Link.(cmd, info ~docs:section_legacy); + Css.(cmd, info ~docs:section_deprecated); + Depends.Odoc_html.(cmd, info ~docs:section_deprecated); ] in let default =