Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Code in Documentation #251

Open
vincent-hugot opened this Issue · 18 comments

5 participants

@vincent-hugot
Collaborator

As discussed on the list.

I tried just passing -keep-code to ocamldoc through myocamlbuild.ml (I don't think there is another way to do so; documentation seems to be a second-class citizen for ocamlbuild), but it didn't work -- and cannot work, because I am pretty certain that ocamlbuild just passes the .mli; you need to pass both the .ml and the .mli for this option to have any effect.

I have no idea how to force ocamlbuild to use the .ml as well as the .mli -- I'm afraid it's not actually possible. So I see two (non-exclusive) courses of action:

  1. patch ocamlbuild to have more options wrt. doc generation. (better for everyone in the long term -- hard)

  2. forgo ocamlbuild and invoke ocamldoc directly. (less satisfying -- much easier)

I'm a very casual user of ocaml{build,doc} however, so I may be missing some trivial solution.

@thelema
Owner
@gasche
Owner

I'm all for option 1, and think you shouldn't be afraid of patching it; ocamlbuild's maintainer, Xavier Clerc, is a very nice person -- albeit very busy, are we all are -- and I'm sure he would consider merging patches upstream if they look reasonable and solve a real issue.

@vincent-hugot
Collaborator

I'll give option 1 a shot, then...

I won't make any promise I can't keep regarding the time frame, so let's say "a while". (I suspect most of that time will be spent gently poking the bazillion makefiles and shell scripts in the distrib with a stick to see if I can coax ocamlbuild into compiling independently of the whole shebang -- which would be nice...)

In the meantime, if anyone feels like trying option 2 or 3 (myocamlbuild) as a temporary workaround, they are welcome to it.

@vincent-hugot vincent-hugot was assigned
@vincent-hugot
Collaborator

Before I forget, I have take taken a look at ocamlbuild's code, and it appears I was wrong in my assumption: ocamlbuild has ocamldoc generate .odocl files from the .ml, and works from there; and the generated .odocl actually contains the source code, I checked.

So perhaps I just had gotten things wrong when I altered myocamlbuild.ml, because I don't see why the -keep-code option wouldn't work from the .odocl. Here is the change I had made:

@@@ -178,7 -178,7 +178,8 @@@
        flag ["ocaml"; "doc"; "extension:html"] &
          (S[A"-t"; A"Batteries user guide";
             A"-intro"; P doc_intro;
--           A"-colorize-code"]);
++           A"-colorize-code";
++           A"-keep-code"]);
@UnixJunkie
Collaborator

The biocaml people may help, they managed to do it for biocaml.
I'll ask them.

@UnixJunkie
Collaborator

I sent a mail to the biocaml ML.

@UnixJunkie
Collaborator

Here is some file related to biocaml's ocamldoc generation:
https://github.com/biocaml/biocaml/blob/v0.3-dev/src/odoc/biohtml.ml

Here is the e-mail related to it on the biocaml ML (by Sebastien Mondet):

All the black-magic is in the (reasonably ugly) ocamldoc plugin: https://github.com/biocaml/biocaml/blob/v0.3-dev/src/odoc/biohtml.ml

Any feedback is welcome:

More stuff could be done:

  • the links to the code of function go to a page containing only the code of that function, it would be nice to point to a specific line of the whole ".ml", so that one can see the context and other functions/types
  • using "with sexp" in the mli files messes ocamldoc up (it's not the plugin, it happens everywhere), so for now one has to write the "val sexp_of_t ... val t_of_sexp", it would be cool to have a nice general solution for boilerplate code.

cheers

Seb

@agarwal
Collaborator

I believe the custom doc generator of Biocaml is not relevant to the original request here, which regards only keeping code. For that, all Biocaml did was bypass ocamlbuild and invoke ocamldoc directly. See Biocaml's Makefile.

@UnixJunkie
Collaborator

Well, whatever allows me to jump to the relevant code from the online
doc of batteries is fine with me.

@UnixJunkie
Collaborator

So, nobody can/want to regenerate the doc with the --inline-code option?

@gasche
Owner

Are you offering to propose a patch to enable this?

It seems that the right thing to do here would be to add support, in ocamlbuild, to pass arbitrary options to ocamldoc, or at least add tags for the few options mentioned here.

@vincent-hugot
Collaborator

the right thing to do here would be to add support, in ocamlbuild, to pass arbitrary options to ocamldoc

Isn't passing arbitrary options (here -keep-code) what the code posted above was supposed to do ? Does ocamlbuild whitelist -t and -intro, and blacklist everything else ? And if not, why does the posted code not achieve the desired result ?

I don't know much -- read: anything -- about the internals of ocamlbuild, but the idea of a whitelist of options seems strange to me.

@gasche
Owner

Isn't passing arbitrary options (here -keep-code) what the code posted above was supposed to do ?

Indeed; I was thinking of tag-level support, but the plugin code you posted should work. Did you try with this modification and get the expected result?

@vincent-hugot
Collaborator

Assuming "this modification" = "the code I posted", then yes, I tried it, and no, I didn't get the expected result. If I had, I would have closed the issue straight away as Fixed, instead of posting the snippet here ;-)

The way I see/saw it:

  • either there is a problem with the odocl format and -keep-code
  • or there is a problem passing -keep-code from ocamlbuild.

I didn't investigate further (combination of dire lack of time and energy, and being probably the least knowledgeable person here on such matters).

@thelema
Owner
@vincent-hugot
Collaborator

I can't even make head nor tail of what I wrote last year:

ocamlbuild has ocamldoc generate .odocl files from the .ml, and works from there; and the generated .odocl actually contains the source code, I checked.

Makes about 0 sense to me now.

@UnixJunkie
Collaborator

Is it possible to have a temporary fix, for example a shell script with invocation
of the right commands so that I can have the doc with the code inlined?

And funny here, I see that there can be problems due to .mli files. Ah! Ah! Ah! :-D

Of course, I don't propose anything related to ocamlbuild: ocamlbuild will fall in oblivion
soon with the advent of obuild (Citrix) and ocp-build (OCamlPro).
Soon, ocamlbuild will be out of my way, permanently.
Good ridance!

@UnixJunkie
Collaborator

read: "obuild and/or ocp-build" in my previous comment

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.