From 437b48a6af980a8194491f8d271a8274c12f5343 Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Fri, 21 Oct 2022 17:51:18 +0200 Subject: [PATCH 1/8] 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/8] 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/8] 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 = From 6fd4447060873a268c0b0d1650318e58e130b52b Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Mon, 24 Oct 2022 10:55:28 +0200 Subject: [PATCH 4/8] Render manpages into the documentation The output of every 'odoc cmd --help' is wrapped into code blocks and concatenated into a page in the documentation. --- doc/dune | 8 ++++++++ doc/gen_manpage/dune | 3 +++ doc/gen_manpage/gen_manpage.ml | 22 ++++++++++++++++++++++ doc/odoc.mld | 1 + 4 files changed, 34 insertions(+) create mode 100644 doc/gen_manpage/dune create mode 100644 doc/gen_manpage/gen_manpage.ml diff --git a/doc/dune b/doc/dune index 3ba2862a19..064c52fe85 100644 --- a/doc/dune +++ b/doc/dune @@ -1,3 +1,11 @@ +(rule + (action + (with-stdout-to + manpage.mld + (pipe-stdout + (run odoc) + (run gen_manpage/gen_manpage.exe))))) + (documentation (package odoc) (mld_files diff --git a/doc/gen_manpage/dune b/doc/gen_manpage/dune new file mode 100644 index 0000000000..8ec6a87bdd --- /dev/null +++ b/doc/gen_manpage/dune @@ -0,0 +1,3 @@ +(executable + (name gen_manpage) + (libraries astring)) diff --git a/doc/gen_manpage/gen_manpage.ml b/doc/gen_manpage/gen_manpage.ml new file mode 100644 index 0000000000..758e70a593 --- /dev/null +++ b/doc/gen_manpage/gen_manpage.ml @@ -0,0 +1,22 @@ +(** Expect the output of [odoc] on standard input. Called like that, Odoc will + output the list of subcommands. *) + +open Astring + +let gen_preamble _cmds = + Printf.printf "{0 Odoc}\n\nOdoc is made of several sub-commands." + +let gen_subcommand cmd = + Printf.printf "\n{1 odoc %s}\n\n{@man[\n%!" cmd; + ignore (Sys.command (Filename.quote_command "odoc" [ cmd; "--help" ])); + Printf.printf "]}\n" + +let () = + let line0 = input_line stdin in + let subcommands = + match String.cut ~sep:":" line0 with + | Some (_, s) -> String.cuts ~sep:"," s |> List.map String.trim + | None -> assert false + in + gen_preamble subcommands; + List.iter gen_subcommand subcommands diff --git a/doc/odoc.mld b/doc/odoc.mld index c88645696d..7767e67995 100644 --- a/doc/odoc.mld +++ b/doc/odoc.mld @@ -50,6 +50,7 @@ To start contributing to [odoc], please see our {{!page-contributing}contributor {1 Page index} The main other pages of this site: +- {!page-manpage} Man pages - {!page-odoc_for_authors} Odoc For Authors - {!page-features} Language Features - {!page-driver} Reference Driver From ba149d589a3a367cef5340f8e1aa920d322fc228 Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Fri, 18 Nov 2022 17:18:33 +0100 Subject: [PATCH 5/8] Commit the generated manpage.mld Allows to build the documentation on <4.10, as the generating program can't run on these versions. Useful feedback when modifying the CLI. Reduce the complexity of the Dune rules for building the doc. Might allow the reference driver to build it, for example. --- doc/dune | 9 +- doc/manpage.mld | 1066 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1074 insertions(+), 1 deletion(-) create mode 100644 doc/manpage.mld diff --git a/doc/dune b/doc/dune index 064c52fe85..9dc5590879 100644 --- a/doc/dune +++ b/doc/dune @@ -1,11 +1,18 @@ (rule (action (with-stdout-to - manpage.mld + manpage.gen.mld (pipe-stdout (run odoc) (run gen_manpage/gen_manpage.exe))))) +(rule + (alias runtest) + (enabled_if + (> %{ocaml_version} 4.10)) + (action + (diff manpage.mld manpage.gen.mld))) + (documentation (package odoc) (mld_files diff --git a/doc/manpage.mld b/doc/manpage.mld new file mode 100644 index 0000000000..b03e09467d --- /dev/null +++ b/doc/manpage.mld @@ -0,0 +1,1066 @@ +{0 Odoc} + +Odoc is made of several sub-commands. +{1 odoc compile} + +{@man[ +NAME + odoc-compile - Compile a .cmti, .cmt, .cmi or .mld file to an .odoc + file. + +SYNOPSIS + odoc compile [--child=CHILD] [--open=MODULE] [--resolve-fwd-refs] + [OPTION]… FILE + +DEPENDENCIES + Dependencies between compilation units is the same as while compiling + the initial OCaml modules. + + Mld pages don't have any dependency. + +ARGUMENTS + --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING + env) + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + --hidden + Mark the unit as hidden. (Useful for files included in module + packs). + + -I DIR + Where to look for required .odoc files. Can be present several + times. + + -o PATH + Output file path. Non-existing intermediate directories are + created. If absent outputs a BASE.odoc file in the same directory + as the input file where 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. + + --parent=PARENT + Parent page or subpage. + + --pkg=PKG, --package=PKG + Package the input is part of. Deprecated: use '--parent' instead. + + --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) + Whether warnings should be printed to stderr. See the errors + command. + + --warn-error (absent ODOC_WARN_ERROR env) + Turn warnings into errors. + + FILE (required) + Input .cmti, .cmt, .cmi or .mld file. + +OPTIONS + -c CHILD, --child=CHILD + Specify the .odoc file as a child. Can be used multiple times. + Only applies to mld files + + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --open=MODULE + Initially open module. Can be used more than once. Defaults to + 'Stdlib' + + -r, --resolve-fwd-refs + Try resolving forward references. + + --version + Show version information. + +ENVIRONMENT + These environment variables affect the execution of compile: + + ODOC_ENABLE_MISSING_ROOT_WARNING + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + ODOC_PRINT_WARNINGS + Whether warnings should be printed to stderr. See the errors + command. + + ODOC_WARN_ERROR + Turn warnings into errors. See option --warn-error. + +]} + +{1 odoc link} + +{@man[ +NAME + odoc-link - Second stage of compilation. Link a .odoc into a .odocl. + +SYNOPSIS + odoc link [--open=MODULE] [OPTION]… FILE.odoc + +DEPENDENCIES + 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. Link steps don't have + dependencies between them. + +ARGUMENTS + --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING + env) + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + -I DIR + Where to look for required .odoc files. Can be present several + times. + + -o PATH.odocl + Output file path. Non-existing intermediate directories are + created. If absent outputs a .odocl file in the same directory as + the input file with the same basename. + + --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) + Whether warnings should be printed to stderr. See the errors + command. + + --warn-error (absent ODOC_WARN_ERROR env) + Turn warnings into errors. + + FILE.odoc (required) + Input file + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --open=MODULE + Initially open module. Can be used more than once. Defaults to + 'Stdlib' + + --version + Show version information. + +ENVIRONMENT + These environment variables affect the execution of link: + + ODOC_ENABLE_MISSING_ROOT_WARNING + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + ODOC_PRINT_WARNINGS + Whether warnings should be printed to stderr. See the errors + command. + + ODOC_WARN_ERROR + Turn warnings into errors. See option --warn-error. + +]} + +{1 odoc html-generate} + +{@man[ +NAME + odoc-html-generate - Generate html files from a .odocl. + +SYNOPSIS + odoc html-generate [OPTION]… FILE.odocl + +ARGUMENTS + --flat + Output HTML files in 'flat' mode, where the hierarchy of modules / + module types / classes and class types are reflected in the + filenames rather than in the directory structure. + + --hidden + Mark the unit as hidden. (Useful for files included in module + packs). + + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + FILE.odocl (required) + Input file. + +OPTIONS + --as-json + EXPERIMENTAL: Output HTML files in 'embeddable json' mode, where + HTML fragments (preamble, content) together with metadata + (uses_katex, breadcrumbs, table of contents) are emitted in JSON + format. + + --closed-details + If this flag is passed
tags (used for includes) will be + closed by default. + + --extra-suffix=SUFFIX + Extra suffix to append to generated filenames. This is intended + for expect tests to use. + + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --indent + Format the output HTML files with indentation. + + --semantic-uris, --pretty-uris + Generate pretty (semantic) links. + + --support-uri=URI + Where to look for support files (e.g. `URI/highlite.pack.js'). + Relative URIs are resolved using `--output-dir' as a target. + + --syntax=SYNTAX (absent=ml or ODOC_SYNTAX env) + Available options: ml | re + + --theme-uri=URI + Where to look for theme files (e.g. `URI/odoc.css'). Relative URIs + are resolved using `--output-dir' as a target. + + --version + Show version information. + +ENVIRONMENT + These environment variables affect the execution of html-generate: + + ODOC_SYNTAX + See option --syntax. + +]} + +{1 odoc support-files} + +{@man[ +NAME + odoc-support-files - Copy the support files (e.g. default theme, + JavaScript files) to the output directory. + +SYNOPSIS + odoc support-files [--without-theme] [OPTION]… + +ARGUMENTS + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + + --without-theme + Don't copy the default theme to output directory. + +]} + +{1 odoc man-generate} + +{@man[ +NAME + odoc-man-generate - Generate man files from a .odocl. + +SYNOPSIS + odoc man-generate [--extra-suffix=SUFFIX] [--syntax=SYNTAX] + [OPTION]… FILE.odocl + +ARGUMENTS + --hidden + Mark the unit as hidden. (Useful for files included in module + packs). + + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + FILE.odocl (required) + Input file. + +OPTIONS + --extra-suffix=SUFFIX + Extra suffix to append to generated filenames. This is intended + for expect tests to use. + + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --syntax=SYNTAX (absent=ml or ODOC_SYNTAX env) + Available options: ml | re + + --version + Show version information. + +ENVIRONMENT + These environment variables affect the execution of man-generate: + + ODOC_SYNTAX + See option --syntax. + +]} + +{1 odoc latex-generate} + +{@man[ +NAME + odoc-latex-generate - Generate latex files from a .odocl. + +SYNOPSIS + odoc latex-generate [--extra-suffix=SUFFIX] [--syntax=SYNTAX] + [--with-children=BOOL] [OPTION]… FILE.odocl + +ARGUMENTS + --hidden + Mark the unit as hidden. (Useful for files included in module + packs). + + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + FILE.odocl (required) + Input file. + +OPTIONS + --extra-suffix=SUFFIX + Extra suffix to append to generated filenames. This is intended + for expect tests to use. + + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --syntax=SYNTAX (absent=ml or ODOC_SYNTAX env) + Available options: ml | re + + --version + Show version information. + + --with-children=BOOL (absent=true) + Include children at the end of the page. + +ENVIRONMENT + These environment variables affect the execution of latex-generate: + + ODOC_SYNTAX + See option --syntax. + +]} + +{1 odoc html-url} + +{@man[ +NAME + odoc-html-url - Resolve a reference and output its corresponding url. + +SYNOPSIS + odoc html-url [OPTION]… REF + +ARGUMENTS + --flat + Output HTML files in 'flat' mode, where the hierarchy of modules / + module types / classes and class types are reflected in the + filenames rather than in the directory structure. + + -I DIR + Where to look for required .odoc files. Can be present several + times. + + REF (required) + The reference to be resolved and whose url to be generated. + +OPTIONS + --as-json + EXPERIMENTAL: Output HTML files in 'embeddable json' mode, where + HTML fragments (preamble, content) together with metadata + (uses_katex, breadcrumbs, table of contents) are emitted in JSON + format. + + --closed-details + If this flag is passed
tags (used for includes) will be + closed by default. + + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --indent + Format the output HTML files with indentation. + + -r VAL, --root-url=VAL + A string to prepend to the generated relative url. A separating / + is added if needed. + + --semantic-uris, --pretty-uris + Generate pretty (semantic) links. + + --support-uri=URI + Where to look for support files (e.g. `URI/highlite.pack.js'). + Relative URIs are resolved using `--output-dir' as a target. + + --theme-uri=URI + Where to look for theme files (e.g. `URI/odoc.css'). Relative URIs + are resolved using `--output-dir' as a target. + + --version + Show version information. + +]} + +{1 odoc latex-url} + +{@man[ +NAME + odoc-latex-url - Resolve a reference and output its corresponding url. + +SYNOPSIS + odoc latex-url [OPTION]… REF + +ARGUMENTS + -I DIR + Where to look for required .odoc files. Can be present several + times. + + REF (required) + The reference to be resolved and whose url to be generated. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + +]} + +{1 odoc support-files-targets} + +{@man[ +NAME + odoc-support-files-targets - Lists the names of the files that odoc + support-files outputs. + +SYNOPSIS + odoc support-files-targets [--without-theme] [OPTION]… + +ARGUMENTS + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + + --without-theme + Don't copy the default theme to output directory. + +]} + +{1 odoc errors} + +{@man[ +NAME + odoc-errors - Print errors that occurred while compiling or linking. + +SYNOPSIS + odoc errors [OPTION]… FILE + +ARGUMENTS + FILE (required) + Input .odoc or .odocl file + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + +]} + +{1 odoc html-targets} + +{@man[ +NAME + odoc-html-targets - Print the files that would be generated by + html-generate. + +SYNOPSIS + odoc html-targets [OPTION]… FILE.odocl + +ARGUMENTS + --flat + Output HTML files in 'flat' mode, where the hierarchy of modules / + module types / classes and class types are reflected in the + filenames rather than in the directory structure. + + -I DIR + For backwards compatibility when processing .odoc rather than + .odocl files. + + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + FILE.odocl (required) + Input file. + +OPTIONS + --as-json + EXPERIMENTAL: Output HTML files in 'embeddable json' mode, where + HTML fragments (preamble, content) together with metadata + (uses_katex, breadcrumbs, table of contents) are emitted in JSON + format. + + --closed-details + If this flag is passed
tags (used for includes) will be + closed by default. + + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --indent + Format the output HTML files with indentation. + + --semantic-uris, --pretty-uris + Generate pretty (semantic) links. + + --support-uri=URI + Where to look for support files (e.g. `URI/highlite.pack.js'). + Relative URIs are resolved using `--output-dir' as a target. + + --theme-uri=URI + Where to look for theme files (e.g. `URI/odoc.css'). Relative URIs + are resolved using `--output-dir' as a target. + + --version + Show version information. + +]} + +{1 odoc man-targets} + +{@man[ +NAME + odoc-man-targets - Print the files that would be generated by + man-generate. + +SYNOPSIS + odoc man-targets [OPTION]… FILE.odocl + +ARGUMENTS + -I DIR + For backwards compatibility when processing .odoc rather than + .odocl files. + + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + FILE.odocl (required) + Input file. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + +]} + +{1 odoc latex-targets} + +{@man[ +NAME + odoc-latex-targets - Print the files that would be generated by + latex-generate. + +SYNOPSIS + odoc latex-targets [--with-children=BOOL] [OPTION]… FILE.odocl + +ARGUMENTS + -I DIR + For backwards compatibility when processing .odoc rather than + .odocl files. + + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + FILE.odocl (required) + Input file. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + + --with-children=BOOL (absent=true) + Include children at the end of the page. + +]} + +{1 odoc compile-deps} + +{@man[ +NAME + odoc-compile-deps - 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. Dependencies between compile steps are + the same as when compiling the ocaml modules. + +SYNOPSIS + odoc compile-deps [OPTION]… file.cm{i,t,ti} + +ARGUMENTS + file.cm{i,t,ti} (required) + Input file + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + +]} + +{1 odoc compile-targets} + +{@man[ +NAME + odoc-compile-targets - Print the name of the file produced by compile. + If -o is passed, the same path is printed but error checking is + performed. + +SYNOPSIS + odoc compile-targets [OPTION]… FILE + +ARGUMENTS + -o PATH + Output file path. Non-existing intermediate directories are + created. If absent outputs a BASE.odoc file in the same directory + as the input file where 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. + + FILE (required) + Input .cmti, .cmt, .cmi or .mld file. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + +]} + +{1 odoc html-fragment} + +{@man[ +NAME + odoc-html-fragment - Generates an html fragment file from an mld one. + +SYNOPSIS + odoc html-fragment [--xref-base-uri=URI] [OPTION]… file.mld + +ARGUMENTS + --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING + env) + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + -I DIR + Where to look for required .odoc files. Can be present several + times. + + -o file.html, --output-file=file.html (absent=/dev/stdout) + Output HTML fragment file. + + --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) + Whether warnings should be printed to stderr. See the errors + command. + + --warn-error (absent ODOC_WARN_ERROR env) + Turn warnings into errors. + + file.mld (required) + Input documentation page file. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + + --xref-base-uri=URI + Base URI used to resolve cross-references. Set this to the root of + the global docset during local development. By default `.' is + used. + +ENVIRONMENT + These environment variables affect the execution of html-fragment: + + ODOC_ENABLE_MISSING_ROOT_WARNING + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + ODOC_PRINT_WARNINGS + Whether warnings should be printed to stderr. See the errors + command. + + ODOC_WARN_ERROR + Turn warnings into errors. See option --warn-error. + +]} + +{1 odoc html} + +{@man[ +NAME + odoc-html - Render html files from a .odoc. link then html-generate + should be used instead. + +SYNOPSIS + odoc html [OPTION]… FILE.odoc + +ARGUMENTS + --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING + env) + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + --flat + Output HTML files in 'flat' mode, where the hierarchy of modules / + module types / classes and class types are reflected in the + filenames rather than in the directory structure. + + --hidden + Mark the unit as hidden. (Useful for files included in module + packs). + + -I DIR + Where to look for required .odoc files. Can be present several + times. + + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) + Whether warnings should be printed to stderr. See the errors + command. + + --warn-error (absent ODOC_WARN_ERROR env) + Turn warnings into errors. + + FILE.odoc (required) + Input file. + +OPTIONS + --as-json + EXPERIMENTAL: Output HTML files in 'embeddable json' mode, where + HTML fragments (preamble, content) together with metadata + (uses_katex, breadcrumbs, table of contents) are emitted in JSON + format. + + --closed-details + If this flag is passed
tags (used for includes) will be + closed by default. + + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --indent + Format the output HTML files with indentation. + + --semantic-uris, --pretty-uris + Generate pretty (semantic) links. + + --support-uri=URI + Where to look for support files (e.g. `URI/highlite.pack.js'). + Relative URIs are resolved using `--output-dir' as a target. + + --syntax=SYNTAX (absent=ml or ODOC_SYNTAX env) + Available options: ml | re + + --theme-uri=URI + Where to look for theme files (e.g. `URI/odoc.css'). Relative URIs + are resolved using `--output-dir' as a target. + + --version + Show version information. + +ENVIRONMENT + These environment variables affect the execution of html: + + ODOC_ENABLE_MISSING_ROOT_WARNING + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + ODOC_PRINT_WARNINGS + Whether warnings should be printed to stderr. See the errors + command. + + ODOC_SYNTAX + See option --syntax. + + ODOC_WARN_ERROR + Turn warnings into errors. See option --warn-error. + +]} + +{1 odoc man} + +{@man[ +NAME + odoc-man - Render man files from a .odoc. link then man-generate + should be used instead. + +SYNOPSIS + odoc man [--syntax=SYNTAX] [OPTION]… FILE.odoc + +ARGUMENTS + --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING + env) + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + --hidden + Mark the unit as hidden. (Useful for files included in module + packs). + + -I DIR + Where to look for required .odoc files. Can be present several + times. + + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) + Whether warnings should be printed to stderr. See the errors + command. + + --warn-error (absent ODOC_WARN_ERROR env) + Turn warnings into errors. + + FILE.odoc (required) + Input file. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --syntax=SYNTAX (absent=ml or ODOC_SYNTAX env) + Available options: ml | re + + --version + Show version information. + +ENVIRONMENT + These environment variables affect the execution of man: + + ODOC_ENABLE_MISSING_ROOT_WARNING + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + ODOC_PRINT_WARNINGS + Whether warnings should be printed to stderr. See the errors + command. + + ODOC_SYNTAX + See option --syntax. + + ODOC_WARN_ERROR + Turn warnings into errors. See option --warn-error. + +]} + +{1 odoc latex} + +{@man[ +NAME + odoc-latex - Render latex files from a .odoc. link then latex-generate + should be used instead. + +SYNOPSIS + odoc latex [--syntax=SYNTAX] [--with-children=BOOL] [OPTION]… + FILE.odoc + +ARGUMENTS + --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING + env) + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + --hidden + Mark the unit as hidden. (Useful for files included in module + packs). + + -I DIR + Where to look for required .odoc files. Can be present several + times. + + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) + Whether warnings should be printed to stderr. See the errors + command. + + --warn-error (absent ODOC_WARN_ERROR env) + Turn warnings into errors. + + FILE.odoc (required) + Input file. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --syntax=SYNTAX (absent=ml or ODOC_SYNTAX env) + Available options: ml | re + + --version + Show version information. + + --with-children=BOOL (absent=true) + Include children at the end of the page. + +ENVIRONMENT + These environment variables affect the execution of latex: + + ODOC_ENABLE_MISSING_ROOT_WARNING + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + ODOC_PRINT_WARNINGS + Whether warnings should be printed to stderr. See the errors + command. + + ODOC_SYNTAX + See option --syntax. + + ODOC_WARN_ERROR + Turn warnings into errors. See option --warn-error. + +]} + +{1 odoc link-deps} + +{@man[ +NAME + odoc-link-deps - Lists a subset of the packages and modules which need + to be in odoc's load path to link the odoc files in the given + directory. Additional packages may be required to resolve all + references. + +SYNOPSIS + odoc link-deps [OPTION]… PKG_DIR + +ARGUMENTS + PKG_DIR (required) + Input directory + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + +]} + +{1 odoc css} + +{@man[ +NAME + odoc-css - DEPRECATED: Use odoc support-files to copy the CSS file for + the default theme. + +SYNOPSIS + odoc css [--without-theme] [OPTION]… + +ARGUMENTS + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + + --without-theme + Don't copy the default theme to output directory. + +]} + +{1 odoc html-deps} + +{@man[ +NAME + odoc-html-deps - DEPRECATED: alias for link-deps + +SYNOPSIS + odoc html-deps [OPTION]… PKG_DIR + +ARGUMENTS + -I DIR + For backwards compatibility. Ignored. + + PKG_DIR (required) + Input directory + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --version + Show version information. + +]} From 3cd32e00524c19074ad7632d53d824922ad9560d Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Fri, 18 Nov 2022 18:49:36 +0100 Subject: [PATCH 6/8] Doc: Manpages: Generate a TOC with summaries Parse the output of 'odoc --help' in a quick and dirty way. It's also possible to parse the name of the section, which is not used yet. 'Unix.open_process_args_in' only works in the intended way on >=4.12. Instead use 'Filename.quote_command', which requires 4.10. --- doc/dune | 6 +- doc/gen_manpage/dune | 4 +- doc/gen_manpage/gen_manpage.ml | 78 ++++- doc/manpage.mld | 524 +++++++++++++++++---------------- 4 files changed, 347 insertions(+), 265 deletions(-) diff --git a/doc/dune b/doc/dune index 9dc5590879..3c265602d4 100644 --- a/doc/dune +++ b/doc/dune @@ -1,10 +1,10 @@ (rule + (deps + (package odoc)) (action (with-stdout-to manpage.gen.mld - (pipe-stdout - (run odoc) - (run gen_manpage/gen_manpage.exe))))) + (run gen_manpage/gen_manpage.exe)))) (rule (alias runtest) diff --git a/doc/gen_manpage/dune b/doc/gen_manpage/dune index 8ec6a87bdd..4bc8b48d3f 100644 --- a/doc/gen_manpage/dune +++ b/doc/gen_manpage/dune @@ -1,3 +1,5 @@ (executable (name gen_manpage) - (libraries astring)) + (enabled_if + (> %{ocaml_version} 4.10)) + (libraries astring unix)) diff --git a/doc/gen_manpage/gen_manpage.ml b/doc/gen_manpage/gen_manpage.ml index 758e70a593..35bbb70945 100644 --- a/doc/gen_manpage/gen_manpage.ml +++ b/doc/gen_manpage/gen_manpage.ml @@ -3,20 +3,76 @@ open Astring -let gen_preamble _cmds = - Printf.printf "{0 Odoc}\n\nOdoc is made of several sub-commands." +let with_process_in cmd args f = + let inp = Unix.open_process_in (Filename.quote_command cmd args) in + let finally () = ignore (Unix.close_process_in inp) in + Fun.protect ~finally (fun () -> f inp) -let gen_subcommand cmd = - Printf.printf "\n{1 odoc %s}\n\n{@man[\n%!" cmd; - ignore (Sys.command (Filename.quote_command "odoc" [ cmd; "--help" ])); +let cat_command cmd args = + with_process_in cmd args (fun inp -> + try + while true do + Printf.printf "%s\n" (input_line inp) + done + with End_of_file -> ()) + +type cmd = { name : string; section : string; summary : string } + +let section_prefix = "COMMANDS: " + +let parse_man' = + let rec collect acc kind = function + | (kind', line) :: tl when kind = kind' -> collect (line :: acc) kind tl + | tl -> (List.rev acc, tl) + in + let rec commands ~section = function + | (`Command, line) :: tl -> + let name = List.hd (String.fields ~empty:false line) in + let _, tl = collect [] `Command tl in + let summary, tl = collect [] `Summary tl in + { name; section; summary = String.concat ~sep:" " summary } + :: commands ~section tl + | tl -> sections tl + and sections = function + | (`Section, line) :: tl when String.is_prefix ~affix:section_prefix line -> + let first = String.length section_prefix in + let section = String.with_range ~first line in + commands ~section tl + | _ :: tl -> sections tl + | [] -> [] + in + sections + +let parse_man inp = + let lines = ref [] in + (try + while true do + let line = input_line inp in + if line = "" then () + else + let kind = + if String.is_prefix ~affix:" " line then `Summary + else if String.is_prefix ~affix:" " line then `Command + else `Section + in + lines := (kind, String.trim line) :: !lines + done + with End_of_file -> ()); + parse_man' (List.rev !lines) + +let gen_preamble cmds = + Printf.printf "{0 Odoc}\n\n{1 odoc}\nOdoc is made of several sub-commands.\n"; + List.iter + (fun { name; summary; _ } -> + Printf.printf "- {!\"odoc-%s\"} %s\n" name summary) + cmds + +let gen_subcommand { name; _ } = + Printf.printf "\n{1 odoc %s}\n\n{@man[\n%!" name; + cat_command "odoc" [ name; "--help" ]; Printf.printf "]}\n" let () = - let line0 = input_line stdin in - let subcommands = - match String.cut ~sep:":" line0 with - | Some (_, s) -> String.cuts ~sep:"," s |> List.map String.trim - | None -> assert false - in + let subcommands = with_process_in "odoc" [ "--help" ] parse_man in gen_preamble subcommands; List.iter gen_subcommand subcommands diff --git a/doc/manpage.mld b/doc/manpage.mld index b03e09467d..f065af4662 100644 --- a/doc/manpage.mld +++ b/doc/manpage.mld @@ -1,6 +1,30 @@ {0 Odoc} +{1 odoc} Odoc is made of several sub-commands. +- {!"odoc-compile"} Compile a .cmti, .cmt, .cmi or .mld file to an .odoc file. +- {!"odoc-html-generate"} Generate html files from a .odocl. +- {!"odoc-link"} Second stage of compilation. Link a .odoc into a .odocl. +- {!"odoc-support-files"} Copy the support files (e.g. default theme, JavaScript files) to the output directory. +- {!"odoc-latex-generate"} Generate latex files from a .odocl. +- {!"odoc-man-generate"} Generate man files from a .odocl. +- {!"odoc-compile-deps"} 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. Dependencies between compile steps are the same as when compiling the ocaml modules. +- {!"odoc-compile-targets"} Print the name of the file produced by compile. If -o is passed, the same path is printed but error checking is performed. +- {!"odoc-errors"} Print errors that occurred while compiling or linking. +- {!"odoc-html-targets"} Print the files that would be generated by html-generate. +- {!"odoc-html-url"} Resolve a reference and output its corresponding url. +- {!"odoc-latex-targets"} Print the files that would be generated by latex-generate. +- {!"odoc-latex-url"} Resolve a reference and output its corresponding url. +- {!"odoc-man-targets"} Print the files that would be generated by man-generate. +- {!"odoc-support-files-targets"} Lists the names of the files that odoc support-files outputs. +- {!"odoc-html"} Render html files from a .odoc. link then html-generate should be used instead. +- {!"odoc-html-fragment"} Generates an html fragment file from an mld one. +- {!"odoc-latex"} Render latex files from a .odoc. link then latex-generate should be used instead. +- {!"odoc-link-deps"} Lists a subset of the packages and modules which need to be in odoc's load path to link the odoc files in the given directory. Additional packages may be required to resolve all references. +- {!"odoc-man"} Render man files from a .odoc. link then man-generate should be used instead. +- {!"odoc-css"} DEPRECATED: Use odoc support-files to copy the CSS file for the default theme. +- {!"odoc-html-deps"} DEPRECATED: alias for link-deps + {1 odoc compile} {@man[ @@ -91,76 +115,6 @@ ENVIRONMENT ]} -{1 odoc link} - -{@man[ -NAME - odoc-link - Second stage of compilation. Link a .odoc into a .odocl. - -SYNOPSIS - odoc link [--open=MODULE] [OPTION]… FILE.odoc - -DEPENDENCIES - 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. Link steps don't have - dependencies between them. - -ARGUMENTS - --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING - env) - Produce a warning when a root is missing. This is usually a build - system problem so is disabled for users by default. - - -I DIR - Where to look for required .odoc files. Can be present several - times. - - -o PATH.odocl - Output file path. Non-existing intermediate directories are - created. If absent outputs a .odocl file in the same directory as - the input file with the same basename. - - --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) - Whether warnings should be printed to stderr. See the errors - command. - - --warn-error (absent ODOC_WARN_ERROR env) - Turn warnings into errors. - - FILE.odoc (required) - Input file - -OPTIONS - --help[=FMT] (default=auto) - Show this help in format FMT. The value FMT must be one of auto, - pager, groff or plain. With auto, the format is pager or plain - whenever the TERM env var is dumb or undefined. - - --open=MODULE - Initially open module. Can be used more than once. Defaults to - 'Stdlib' - - --version - Show version information. - -ENVIRONMENT - These environment variables affect the execution of link: - - ODOC_ENABLE_MISSING_ROOT_WARNING - Produce a warning when a root is missing. This is usually a build - system problem so is disabled for users by default. - - ODOC_PRINT_WARNINGS - Whether warnings should be printed to stderr. See the errors - command. - - ODOC_WARN_ERROR - Turn warnings into errors. See option --warn-error. - -]} - {1 odoc html-generate} {@man[ @@ -234,19 +188,46 @@ ENVIRONMENT ]} -{1 odoc support-files} +{1 odoc link} {@man[ NAME - odoc-support-files - Copy the support files (e.g. default theme, - JavaScript files) to the output directory. + odoc-link - Second stage of compilation. Link a .odoc into a .odocl. SYNOPSIS - odoc support-files [--without-theme] [OPTION]… + odoc link [--open=MODULE] [OPTION]… FILE.odoc + +DEPENDENCIES + 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. Link steps don't have + dependencies between them. ARGUMENTS - -o DIR, --output-dir=DIR (required) - Output directory where the HTML tree is expected to be saved. + --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING + env) + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + -I DIR + Where to look for required .odoc files. Can be present several + times. + + -o PATH.odocl + Output file path. Non-existing intermediate directories are + created. If absent outputs a .odocl file in the same directory as + the input file with the same basename. + + --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) + Whether warnings should be printed to stderr. See the errors + command. + + --warn-error (absent ODOC_WARN_ERROR env) + Turn warnings into errors. + + FILE.odoc (required) + Input file OPTIONS --help[=FMT] (default=auto) @@ -254,56 +235,54 @@ OPTIONS pager, groff or plain. With auto, the format is pager or plain whenever the TERM env var is dumb or undefined. + --open=MODULE + Initially open module. Can be used more than once. Defaults to + 'Stdlib' + --version Show version information. - --without-theme - Don't copy the default theme to output directory. +ENVIRONMENT + These environment variables affect the execution of link: + + ODOC_ENABLE_MISSING_ROOT_WARNING + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + ODOC_PRINT_WARNINGS + Whether warnings should be printed to stderr. See the errors + command. + + ODOC_WARN_ERROR + Turn warnings into errors. See option --warn-error. ]} -{1 odoc man-generate} +{1 odoc support-files} {@man[ NAME - odoc-man-generate - Generate man files from a .odocl. + odoc-support-files - Copy the support files (e.g. default theme, + JavaScript files) to the output directory. SYNOPSIS - odoc man-generate [--extra-suffix=SUFFIX] [--syntax=SYNTAX] - [OPTION]… FILE.odocl + odoc support-files [--without-theme] [OPTION]… ARGUMENTS - --hidden - Mark the unit as hidden. (Useful for files included in module - packs). - -o DIR, --output-dir=DIR (required) Output directory where the HTML tree is expected to be saved. - FILE.odocl (required) - Input file. - OPTIONS - --extra-suffix=SUFFIX - Extra suffix to append to generated filenames. This is intended - for expect tests to use. - --help[=FMT] (default=auto) Show this help in format FMT. The value FMT must be one of auto, pager, groff or plain. With auto, the format is pager or plain whenever the TERM env var is dumb or undefined. - --syntax=SYNTAX (absent=ml or ODOC_SYNTAX env) - Available options: ml | re - --version Show version information. -ENVIRONMENT - These environment variables affect the execution of man-generate: - - ODOC_SYNTAX - See option --syntax. + --without-theme + Don't copy the default theme to output directory. ]} @@ -355,83 +334,66 @@ ENVIRONMENT ]} -{1 odoc html-url} +{1 odoc man-generate} {@man[ NAME - odoc-html-url - Resolve a reference and output its corresponding url. + odoc-man-generate - Generate man files from a .odocl. SYNOPSIS - odoc html-url [OPTION]… REF + odoc man-generate [--extra-suffix=SUFFIX] [--syntax=SYNTAX] + [OPTION]… FILE.odocl ARGUMENTS - --flat - Output HTML files in 'flat' mode, where the hierarchy of modules / - module types / classes and class types are reflected in the - filenames rather than in the directory structure. + --hidden + Mark the unit as hidden. (Useful for files included in module + packs). - -I DIR - Where to look for required .odoc files. Can be present several - times. + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. - REF (required) - The reference to be resolved and whose url to be generated. + FILE.odocl (required) + Input file. OPTIONS - --as-json - EXPERIMENTAL: Output HTML files in 'embeddable json' mode, where - HTML fragments (preamble, content) together with metadata - (uses_katex, breadcrumbs, table of contents) are emitted in JSON - format. - - --closed-details - If this flag is passed
tags (used for includes) will be - closed by default. + --extra-suffix=SUFFIX + Extra suffix to append to generated filenames. This is intended + for expect tests to use. --help[=FMT] (default=auto) Show this help in format FMT. The value FMT must be one of auto, pager, groff or plain. With auto, the format is pager or plain whenever the TERM env var is dumb or undefined. - --indent - Format the output HTML files with indentation. - - -r VAL, --root-url=VAL - A string to prepend to the generated relative url. A separating / - is added if needed. - - --semantic-uris, --pretty-uris - Generate pretty (semantic) links. - - --support-uri=URI - Where to look for support files (e.g. `URI/highlite.pack.js'). - Relative URIs are resolved using `--output-dir' as a target. - - --theme-uri=URI - Where to look for theme files (e.g. `URI/odoc.css'). Relative URIs - are resolved using `--output-dir' as a target. + --syntax=SYNTAX (absent=ml or ODOC_SYNTAX env) + Available options: ml | re --version Show version information. +ENVIRONMENT + These environment variables affect the execution of man-generate: + + ODOC_SYNTAX + See option --syntax. + ]} -{1 odoc latex-url} +{1 odoc compile-deps} {@man[ NAME - odoc-latex-url - Resolve a reference and output its corresponding url. + odoc-compile-deps - 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. Dependencies between compile steps are + the same as when compiling the ocaml modules. SYNOPSIS - odoc latex-url [OPTION]… REF + odoc compile-deps [OPTION]… file.cm{i,t,ti} ARGUMENTS - -I DIR - Where to look for required .odoc files. Can be present several - times. - - REF (required) - The reference to be resolved and whose url to be generated. + file.cm{i,t,ti} (required) + Input file OPTIONS --help[=FMT] (default=auto) @@ -444,19 +406,27 @@ OPTIONS ]} -{1 odoc support-files-targets} +{1 odoc compile-targets} {@man[ NAME - odoc-support-files-targets - Lists the names of the files that odoc - support-files outputs. + odoc-compile-targets - Print the name of the file produced by compile. + If -o is passed, the same path is printed but error checking is + performed. SYNOPSIS - odoc support-files-targets [--without-theme] [OPTION]… + odoc compile-targets [OPTION]… FILE ARGUMENTS - -o DIR, --output-dir=DIR (required) - Output directory where the HTML tree is expected to be saved. + -o PATH + Output file path. Non-existing intermediate directories are + created. If absent outputs a BASE.odoc file in the same directory + as the input file where 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. + + FILE (required) + Input .cmti, .cmt, .cmi or .mld file. OPTIONS --help[=FMT] (default=auto) @@ -467,9 +437,6 @@ OPTIONS --version Show version information. - --without-theme - Don't copy the default theme to output directory. - ]} {1 odoc errors} @@ -557,33 +524,62 @@ OPTIONS ]} -{1 odoc man-targets} +{1 odoc html-url} {@man[ NAME - odoc-man-targets - Print the files that would be generated by - man-generate. + odoc-html-url - Resolve a reference and output its corresponding url. SYNOPSIS - odoc man-targets [OPTION]… FILE.odocl + odoc html-url [OPTION]… REF ARGUMENTS - -I DIR - For backwards compatibility when processing .odoc rather than - .odocl files. + --flat + Output HTML files in 'flat' mode, where the hierarchy of modules / + module types / classes and class types are reflected in the + filenames rather than in the directory structure. - -o DIR, --output-dir=DIR (required) - Output directory where the HTML tree is expected to be saved. + -I DIR + Where to look for required .odoc files. Can be present several + times. - FILE.odocl (required) - Input file. + REF (required) + The reference to be resolved and whose url to be generated. OPTIONS + --as-json + EXPERIMENTAL: Output HTML files in 'embeddable json' mode, where + HTML fragments (preamble, content) together with metadata + (uses_katex, breadcrumbs, table of contents) are emitted in JSON + format. + + --closed-details + If this flag is passed
tags (used for includes) will be + closed by default. + --help[=FMT] (default=auto) Show this help in format FMT. The value FMT must be one of auto, pager, groff or plain. With auto, the format is pager or plain whenever the TERM env var is dumb or undefined. + --indent + Format the output HTML files with indentation. + + -r VAL, --root-url=VAL + A string to prepend to the generated relative url. A separating / + is added if needed. + + --semantic-uris, --pretty-uris + Generate pretty (semantic) links. + + --support-uri=URI + Where to look for support files (e.g. `URI/highlite.pack.js'). + Relative URIs are resolved using `--output-dir' as a target. + + --theme-uri=URI + Where to look for theme files (e.g. `URI/odoc.css'). Relative URIs + are resolved using `--output-dir' as a target. + --version Show version information. @@ -624,21 +620,22 @@ OPTIONS ]} -{1 odoc compile-deps} +{1 odoc latex-url} {@man[ NAME - odoc-compile-deps - 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. Dependencies between compile steps are - the same as when compiling the ocaml modules. + odoc-latex-url - Resolve a reference and output its corresponding url. SYNOPSIS - odoc compile-deps [OPTION]… file.cm{i,t,ti} + odoc latex-url [OPTION]… REF ARGUMENTS - file.cm{i,t,ti} (required) - Input file + -I DIR + Where to look for required .odoc files. Can be present several + times. + + REF (required) + The reference to be resolved and whose url to be generated. OPTIONS --help[=FMT] (default=auto) @@ -651,27 +648,26 @@ OPTIONS ]} -{1 odoc compile-targets} +{1 odoc man-targets} {@man[ NAME - odoc-compile-targets - Print the name of the file produced by compile. - If -o is passed, the same path is printed but error checking is - performed. + odoc-man-targets - Print the files that would be generated by + man-generate. SYNOPSIS - odoc compile-targets [OPTION]… FILE + odoc man-targets [OPTION]… FILE.odocl ARGUMENTS - -o PATH - Output file path. Non-existing intermediate directories are - created. If absent outputs a BASE.odoc file in the same directory - as the input file where 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. + -I DIR + For backwards compatibility when processing .odoc rather than + .odocl files. - FILE (required) - Input .cmti, .cmt, .cmi or .mld file. + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + FILE.odocl (required) + Input file. OPTIONS --help[=FMT] (default=auto) @@ -684,37 +680,19 @@ OPTIONS ]} -{1 odoc html-fragment} +{1 odoc support-files-targets} {@man[ NAME - odoc-html-fragment - Generates an html fragment file from an mld one. + odoc-support-files-targets - Lists the names of the files that odoc + support-files outputs. SYNOPSIS - odoc html-fragment [--xref-base-uri=URI] [OPTION]… file.mld + odoc support-files-targets [--without-theme] [OPTION]… ARGUMENTS - --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING - env) - Produce a warning when a root is missing. This is usually a build - system problem so is disabled for users by default. - - -I DIR - Where to look for required .odoc files. Can be present several - times. - - -o file.html, --output-file=file.html (absent=/dev/stdout) - Output HTML fragment file. - - --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) - Whether warnings should be printed to stderr. See the errors - command. - - --warn-error (absent ODOC_WARN_ERROR env) - Turn warnings into errors. - - file.mld (required) - Input documentation page file. + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. OPTIONS --help[=FMT] (default=auto) @@ -725,24 +703,8 @@ OPTIONS --version Show version information. - --xref-base-uri=URI - Base URI used to resolve cross-references. Set this to the root of - the global docset during local development. By default `.' is - used. - -ENVIRONMENT - These environment variables affect the execution of html-fragment: - - ODOC_ENABLE_MISSING_ROOT_WARNING - Produce a warning when a root is missing. This is usually a build - system problem so is disabled for users by default. - - ODOC_PRINT_WARNINGS - Whether warnings should be printed to stderr. See the errors - command. - - ODOC_WARN_ERROR - Turn warnings into errors. See option --warn-error. + --without-theme + Don't copy the default theme to output directory. ]} @@ -843,15 +805,14 @@ ENVIRONMENT ]} -{1 odoc man} +{1 odoc html-fragment} {@man[ NAME - odoc-man - Render man files from a .odoc. link then man-generate - should be used instead. + odoc-html-fragment - Generates an html fragment file from an mld one. SYNOPSIS - odoc man [--syntax=SYNTAX] [OPTION]… FILE.odoc + odoc html-fragment [--xref-base-uri=URI] [OPTION]… file.mld ARGUMENTS --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING @@ -859,16 +820,12 @@ ARGUMENTS Produce a warning when a root is missing. This is usually a build system problem so is disabled for users by default. - --hidden - Mark the unit as hidden. (Useful for files included in module - packs). - -I DIR Where to look for required .odoc files. Can be present several times. - -o DIR, --output-dir=DIR (required) - Output directory where the HTML tree is expected to be saved. + -o file.html, --output-file=file.html (absent=/dev/stdout) + Output HTML fragment file. --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) Whether warnings should be printed to stderr. See the errors @@ -877,8 +834,8 @@ ARGUMENTS --warn-error (absent ODOC_WARN_ERROR env) Turn warnings into errors. - FILE.odoc (required) - Input file. + file.mld (required) + Input documentation page file. OPTIONS --help[=FMT] (default=auto) @@ -886,14 +843,16 @@ OPTIONS pager, groff or plain. With auto, the format is pager or plain whenever the TERM env var is dumb or undefined. - --syntax=SYNTAX (absent=ml or ODOC_SYNTAX env) - Available options: ml | re - --version Show version information. + --xref-base-uri=URI + Base URI used to resolve cross-references. Set this to the root of + the global docset during local development. By default `.' is + used. + ENVIRONMENT - These environment variables affect the execution of man: + These environment variables affect the execution of html-fragment: ODOC_ENABLE_MISSING_ROOT_WARNING Produce a warning when a root is missing. This is usually a build @@ -903,9 +862,6 @@ ENVIRONMENT Whether warnings should be printed to stderr. See the errors command. - ODOC_SYNTAX - See option --syntax. - ODOC_WARN_ERROR Turn warnings into errors. See option --warn-error. @@ -1010,6 +966,74 @@ OPTIONS ]} +{1 odoc man} + +{@man[ +NAME + odoc-man - Render man files from a .odoc. link then man-generate + should be used instead. + +SYNOPSIS + odoc man [--syntax=SYNTAX] [OPTION]… FILE.odoc + +ARGUMENTS + --enable-missing-root-warning (absent ODOC_ENABLE_MISSING_ROOT_WARNING + env) + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + --hidden + Mark the unit as hidden. (Useful for files included in module + packs). + + -I DIR + Where to look for required .odoc files. Can be present several + times. + + -o DIR, --output-dir=DIR (required) + Output directory where the HTML tree is expected to be saved. + + --print-warnings=VAL (absent=true or ODOC_PRINT_WARNINGS env) + Whether warnings should be printed to stderr. See the errors + command. + + --warn-error (absent ODOC_WARN_ERROR env) + Turn warnings into errors. + + FILE.odoc (required) + Input file. + +OPTIONS + --help[=FMT] (default=auto) + Show this help in format FMT. The value FMT must be one of auto, + pager, groff or plain. With auto, the format is pager or plain + whenever the TERM env var is dumb or undefined. + + --syntax=SYNTAX (absent=ml or ODOC_SYNTAX env) + Available options: ml | re + + --version + Show version information. + +ENVIRONMENT + These environment variables affect the execution of man: + + ODOC_ENABLE_MISSING_ROOT_WARNING + Produce a warning when a root is missing. This is usually a build + system problem so is disabled for users by default. + + ODOC_PRINT_WARNINGS + Whether warnings should be printed to stderr. See the errors + command. + + ODOC_SYNTAX + See option --syntax. + + ODOC_WARN_ERROR + Turn warnings into errors. See option --warn-error. + +]} + {1 odoc css} {@man[ From 25a90f3d92e12fd185ff023d3aceb13d93bd14d2 Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Mon, 21 Nov 2022 09:28:11 +0100 Subject: [PATCH 7/8] Doc: Manpages: Group commands by sections Sections are used to group commands by generating doc sections. The TOC looks more readable. The first section is also nicer with some separations between the list items. --- doc/gen_manpage/gen_manpage.ml | 49 +++++++++++++++--------- doc/manpage.mld | 69 +++++++++++++++++++++++----------- 2 files changed, 78 insertions(+), 40 deletions(-) diff --git a/doc/gen_manpage/gen_manpage.ml b/doc/gen_manpage/gen_manpage.ml index 35bbb70945..2e6735ed75 100644 --- a/doc/gen_manpage/gen_manpage.ml +++ b/doc/gen_manpage/gen_manpage.ml @@ -16,7 +16,7 @@ let cat_command cmd args = done with End_of_file -> ()) -type cmd = { name : string; section : string; summary : string } +type cmd = { name : string; summary : string } let section_prefix = "COMMANDS: " @@ -25,19 +25,19 @@ let parse_man' = | (kind', line) :: tl when kind = kind' -> collect (line :: acc) kind tl | tl -> (List.rev acc, tl) in - let rec commands ~section = function + let rec commands acc = function | (`Command, line) :: tl -> let name = List.hd (String.fields ~empty:false line) in let _, tl = collect [] `Command tl in let summary, tl = collect [] `Summary tl in - { name; section; summary = String.concat ~sep:" " summary } - :: commands ~section tl - | tl -> sections tl + commands ({ name; summary = String.concat ~sep:" " summary } :: acc) tl + | tl -> (List.rev acc, tl) and sections = function | (`Section, line) :: tl when String.is_prefix ~affix:section_prefix line -> let first = String.length section_prefix in let section = String.with_range ~first line in - commands ~section tl + let cmds, tl = commands [] tl in + (section, cmds) :: sections tl | _ :: tl -> sections tl | [] -> [] in @@ -60,19 +60,32 @@ let parse_man inp = with End_of_file -> ()); parse_man' (List.rev !lines) -let gen_preamble cmds = - Printf.printf "{0 Odoc}\n\n{1 odoc}\nOdoc is made of several sub-commands.\n"; +open Printf + +let gen_preamble sections = + printf "{0 Odoc}\n\n{1 odoc}\nOdoc is made of several sub-commands.\n"; List.iter - (fun { name; summary; _ } -> - Printf.printf "- {!\"odoc-%s\"} %s\n" name summary) - cmds + (fun (section, cmds) -> + printf "\n%s:\n\n" section; + List.iter + (fun { name; summary; _ } -> + printf "- {!\"odoc-%s\"} %s\n" name summary) + cmds) + sections -let gen_subcommand { name; _ } = - Printf.printf "\n{1 odoc %s}\n\n{@man[\n%!" name; - cat_command "odoc" [ name; "--help" ]; - Printf.printf "]}\n" +let gen_manpages sections = + List.iter + (fun (section, cmds) -> + printf "\n{1 %s}\n" section; + List.iter + (fun { name; _ } -> + printf "\n{2 odoc %s}\n\n{@man[\n%!" name; + cat_command "odoc" [ name; "--help" ]; + printf "]}\n") + cmds) + sections let () = - let subcommands = with_process_in "odoc" [ "--help" ] parse_man in - gen_preamble subcommands; - List.iter gen_subcommand subcommands + let sections = with_process_in "odoc" [ "--help" ] parse_man in + gen_preamble sections; + gen_manpages sections diff --git a/doc/manpage.mld b/doc/manpage.mld index f065af4662..ecd80238d3 100644 --- a/doc/manpage.mld +++ b/doc/manpage.mld @@ -2,12 +2,21 @@ {1 odoc} Odoc is made of several sub-commands. + +Compilation pipeline: + - {!"odoc-compile"} Compile a .cmti, .cmt, .cmi or .mld file to an .odoc file. - {!"odoc-html-generate"} Generate html files from a .odocl. - {!"odoc-link"} Second stage of compilation. Link a .odoc into a .odocl. - {!"odoc-support-files"} Copy the support files (e.g. default theme, JavaScript files) to the output directory. + +Alternative generators: + - {!"odoc-latex-generate"} Generate latex files from a .odocl. - {!"odoc-man-generate"} Generate man files from a .odocl. + +Scripting: + - {!"odoc-compile-deps"} 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. Dependencies between compile steps are the same as when compiling the ocaml modules. - {!"odoc-compile-targets"} Print the name of the file produced by compile. If -o is passed, the same path is printed but error checking is performed. - {!"odoc-errors"} Print errors that occurred while compiling or linking. @@ -17,15 +26,23 @@ Odoc is made of several sub-commands. - {!"odoc-latex-url"} Resolve a reference and output its corresponding url. - {!"odoc-man-targets"} Print the files that would be generated by man-generate. - {!"odoc-support-files-targets"} Lists the names of the files that odoc support-files outputs. + +Legacy pipeline: + - {!"odoc-html"} Render html files from a .odoc. link then html-generate should be used instead. - {!"odoc-html-fragment"} Generates an html fragment file from an mld one. - {!"odoc-latex"} Render latex files from a .odoc. link then latex-generate should be used instead. - {!"odoc-link-deps"} Lists a subset of the packages and modules which need to be in odoc's load path to link the odoc files in the given directory. Additional packages may be required to resolve all references. - {!"odoc-man"} Render man files from a .odoc. link then man-generate should be used instead. + +Deprecated: + - {!"odoc-css"} DEPRECATED: Use odoc support-files to copy the CSS file for the default theme. - {!"odoc-html-deps"} DEPRECATED: alias for link-deps -{1 odoc compile} +{1 Compilation pipeline} + +{2 odoc compile} {@man[ NAME @@ -115,7 +132,7 @@ ENVIRONMENT ]} -{1 odoc html-generate} +{2 odoc html-generate} {@man[ NAME @@ -188,7 +205,7 @@ ENVIRONMENT ]} -{1 odoc link} +{2 odoc link} {@man[ NAME @@ -258,7 +275,7 @@ ENVIRONMENT ]} -{1 odoc support-files} +{2 odoc support-files} {@man[ NAME @@ -286,7 +303,9 @@ OPTIONS ]} -{1 odoc latex-generate} +{1 Alternative generators} + +{2 odoc latex-generate} {@man[ NAME @@ -334,7 +353,7 @@ ENVIRONMENT ]} -{1 odoc man-generate} +{2 odoc man-generate} {@man[ NAME @@ -379,7 +398,9 @@ ENVIRONMENT ]} -{1 odoc compile-deps} +{1 Scripting} + +{2 odoc compile-deps} {@man[ NAME @@ -406,7 +427,7 @@ OPTIONS ]} -{1 odoc compile-targets} +{2 odoc compile-targets} {@man[ NAME @@ -439,7 +460,7 @@ OPTIONS ]} -{1 odoc errors} +{2 odoc errors} {@man[ NAME @@ -463,7 +484,7 @@ OPTIONS ]} -{1 odoc html-targets} +{2 odoc html-targets} {@man[ NAME @@ -524,7 +545,7 @@ OPTIONS ]} -{1 odoc html-url} +{2 odoc html-url} {@man[ NAME @@ -585,7 +606,7 @@ OPTIONS ]} -{1 odoc latex-targets} +{2 odoc latex-targets} {@man[ NAME @@ -620,7 +641,7 @@ OPTIONS ]} -{1 odoc latex-url} +{2 odoc latex-url} {@man[ NAME @@ -648,7 +669,7 @@ OPTIONS ]} -{1 odoc man-targets} +{2 odoc man-targets} {@man[ NAME @@ -680,7 +701,7 @@ OPTIONS ]} -{1 odoc support-files-targets} +{2 odoc support-files-targets} {@man[ NAME @@ -708,7 +729,9 @@ OPTIONS ]} -{1 odoc html} +{1 Legacy pipeline} + +{2 odoc html} {@man[ NAME @@ -805,7 +828,7 @@ ENVIRONMENT ]} -{1 odoc html-fragment} +{2 odoc html-fragment} {@man[ NAME @@ -867,7 +890,7 @@ ENVIRONMENT ]} -{1 odoc latex} +{2 odoc latex} {@man[ NAME @@ -939,7 +962,7 @@ ENVIRONMENT ]} -{1 odoc link-deps} +{2 odoc link-deps} {@man[ NAME @@ -966,7 +989,7 @@ OPTIONS ]} -{1 odoc man} +{2 odoc man} {@man[ NAME @@ -1034,7 +1057,9 @@ ENVIRONMENT ]} -{1 odoc css} +{1 Deprecated} + +{2 odoc css} {@man[ NAME @@ -1062,7 +1087,7 @@ OPTIONS ]} -{1 odoc html-deps} +{2 odoc html-deps} {@man[ NAME From eeb8d799d3deb502b92b099701e4f86b16ca0b26 Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Tue, 29 Nov 2022 16:30:02 +0100 Subject: [PATCH 8/8] Disable manpage generation on @runtest It randomly break on different targets. It should be replaced by something that do not depend on parsing textual output before it can be enabled again by default. --- doc/dune | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/dune b/doc/dune index 3c265602d4..85918b0210 100644 --- a/doc/dune +++ b/doc/dune @@ -6,8 +6,12 @@ manpage.gen.mld (run gen_manpage/gen_manpage.exe)))) +; Ideally, this would be run with the other tests. Currently depend on the +; exact output of 'odoc --help', which is not stable and would break the test +; too often. + (rule - (alias runtest) + (alias docmanpage) (enabled_if (> %{ocaml_version} 4.10)) (action