使ocamlbuild能同时传递.ml和.mli文件给ocamldoc

Question

我希望在我的生成文档中包含源代码。当我通过命令行调用ocamldoc时，这是有效的，例如：ocamldoc -I _build -html -keep-code -colorize-code *.{ml,mli} -d .docdir。然而，我试图将其与ocamlbuild集成时出现了问题。

我在myocamlbuild.ml中使用以下代码：

open Ocamlbuild_plugin;;

dispatch begin function
  | After_options ->
      Options.ocamldoc := S[A"ocamldoc"; A"-keep-code"; A"-colorize-code"]
  | _ -> ()
end

但是这仅包括没有相应接口文件的文件的源代码 - 与此处所说的相反，看起来ocamlbuild拒绝将.ml文件传递给ocamldoc当存在一个.mli文件时。有没有办法诱导ocamlbuild做我想要的事情？

- Mikhail Glushenkov

Answer 1

由于我需要破解一些东西来完成类似的工作，因此如果我在这里发布它作为答案（至少在OCamlbuild具备该功能之前），可能会有所帮助。因此，这是我myocamlbuild.ml的相关部分：

open Ocamlbuild_plugin;;

dispatch begin function
  | After_rules ->
     (* Using both .ml and .mli files to build documentation: *)
     rule "ocaml: ml & mli -> odoc"
       ~insert:`top
       ~tags:["ocaml"; "doc"; "doc_use_interf_n_implem"]
       ~prod:"%.odoc"
       (* "%.cmo" so that cmis of ml dependencies are already built: *)
       ~deps:["%.ml"; "%.mli"; "%.cmo"]
       begin fun env build ->
         let mli = env "%.mli" and ml = env "%.ml" and odoc = env "%.odoc" in
         let tags =
           (Tags.union (tags_of_pathname mli) (tags_of_pathname ml))
           ++"doc_use_interf_n_implem"++"ocaml"++"doc" in
         let include_dirs = Pathname.include_dirs_of (Pathname.dirname ml) in
         let include_flags =
           List.fold_right (fun p acc -> A"-I" :: A p :: acc) include_dirs [] in
         Cmd (S [!Options.ocamldoc; A"-dump"; Px odoc;
                 T (tags++"doc"++"pp"); S (include_flags);
                 A"-intf"; P mli; A"-impl"; P ml])
       end;

    (* Specifying merge options with tags: *)
    pflag ["ocaml"; "doc"; "doc_use_interf_n_implem"] "merge"
      (fun s -> S[A"-m"; A s]);
end

然后，将标签doc_use_interf_n_implem添加到需要从实现和接口生成文档的.ml和/或.mli文件中即可。使用上述代码，也可以通过添加诸如merge(A)（以合并所有内容）之类的标签来添加合并选项。

请注意，这是一种可能会在复杂项目中出现问题的黑客技巧。特别是，我没有测试过它与camlp[45]处理的文件或OCamlbuild 4.00.1以外版本的兼容性。

- nberth

Answer 2

看起来OCamlbuild目前不支持这种功能。你能否在错误跟踪系统上提交一个特性请求？

- gasche