1

I am using the Oasis build system for an OCaml projects and I would like to build the documentation and to get it in ${projectroot}/doc/api/.

For now, my _oasis file is something like that:

OASISFormat: 0.4
Name: MyProject
Version: 0.1alpha
Plugins: META (0.4)
BuildTools: ocamlbuild
AlphaFeatures: ocamlbuild_more_args

PostDistcleanCommand: $rm _tags myocamlbuild.ml setup.ml setup.data

Document api
Title: MyProject API
Type: ocamlbuild (0.4)
BuildTools: ocamldoc
XOCamlbuildPath: src
XOCamlbuildExtraArgs: -docflags -d,doc/api,-colorize-code,-charset,utf-8

Then, I run the following commands:

$> oasis setup
$> ocaml setup.ml -configure
...
$> ocaml setup.ml -doc
...

Then, I get a link api.docdir/ --> _build/src/api.docdir/ at the top directory of the project linking to the documentation that I expect. But, it seems that the -d doc/api with the extra-arguments has not been taken into account.

So, what did I miss ? Because, I am a bit running out of ideas here...

perror
  • 7,071
  • 16
  • 58
  • 85
  • I suspect you can't do what you want. oasis uses ocamlbuild and this is [the way](http://caml.inria.fr/pub/docs/manual-ocaml/ocamlbuild.html#sec405) ocamldoc generation works with ocamlbuild. If you write your api.odocl file in doc then the documentation will be in doc/api.docdir but I don't know if you can do this with oasis. – Daniel Bünzli Jul 31 '15 at 12:49
  • Having `doc/api.docdir` would be also fine for me. It is more about the fact to have everything at the project rootdir that disturb me. But, as I am quite new to OCaml, if having the link at the topdir is the usual way to do, I will conform to it. I'm just learning. – perror Jul 31 '15 at 14:32
  • 1
    The symlink is just a convenience you can avoid it by invoking ocamlbuild with `--no-links`. – Daniel Bünzli Jul 31 '15 at 14:36
  • Beware, the option is `-no-links` (a unique dash at start). – perror Jul 31 '15 at 15:14

1 Answers1

2

A proper way would be to use install command that will copy your documentation (as well as other data) to a proper place, that is customizable with configure command, or with InstallDir field.

Also, if you still want to migrate your documentation inside your project, without doing the installation, then you can use PostCommand field, and use a small script (or just a one-liner) to move your documentation in a better place.

ivg
  • 34,431
  • 2
  • 35
  • 63
  • I guess that this is the way to do it. I am not really found of having a `PostCommand` but if it does the job, it's okay for me. Now, I better understand why you had this `bapdoc.ml` in BAP. :-) – perror Jul 31 '15 at 14:34
  • the main reason, is that `ocamldoc` behaves incorrectly in the presence of camlp4 syntax extensions. So this script just performs preprocessing to remove preprocessing :) – ivg Jul 31 '15 at 14:45
  • Ah, thanks for that comment because I am not yet using camlp4 and that might help in the future ! – perror Jul 31 '15 at 14:52
  • `install` and `configure` commands for what program, used how? – Mars May 12 '17 at 17:49