search

ocaml / odoc

Documentation compiler for OCaml and Reason
Other
321 stars 90 forks source link

Improve support-file management #155

Closed rizo closed 4 years ago

rizo commented 6 years ago

Currently this is how odoc manages support files (CSS+JS):

Essentially it copies the content of the support files into OCaml modules that get linked with the odoc binary. This avoids having them as a file-system dependency making odoc effectively portable.

As we add more files (like fonts or other JS files) it will become a bit messier to do this because of all the boilerplate. I suggest to bundle the files into a directory for easier distribution but to preserve portability we might need to use something similar to https://github.com/mirage/ocaml-crunch.

rizo commented 6 years ago

I think we need to make a decision regarding this. I'd like to add more support files to odoc and the current approach is not ideal.

@dbuenzli noted that odoc is already not portable across different compiler versions. Which to me implies that odoc is better distributed as part of a particular opam switch. Unless we want to invest time into making it portable in the future.

I believe we have two options:

  1. Assume odoc is not portable and get rid of embedded support/theme files. Both would be stored as simple directories and copied over to the HTML output directory by default.
  2. Integrate a tool like ocaml-crunch to distribute the support/theme files. This could either mean adding ocaml-crunch as a dependency or reimplementing it in odoc.

What do you think?

P.S. Just a reminder that in https://github.com/ocaml/odoc/pull/154 we decided to separate "assets" into "support files" and "theme files", leaving "assets" for files embedded in documentation.

aantron commented 6 years ago

@rizo Even though odoc is not portable across compiler versions, there is still (IMO) a reason to embed the files. At some future time, we may want to suggest using odoc with BuckleScript and NPM. It will be easier to do this if odoc does not depend on directories in opam (or anywhere), at least for basic odoc usage.

BuckleScript is also usually fixed at one version of OCaml, so we would be compiling and distributing odoc binaries for the corresponding compiler version. Lack of portability is not a problem here, and indeed, I think it is a red herring for this issue.

So, I support some variant of (2).

aantron commented 6 years ago

Actually, since integrating ocaml-crunch into odoc takes work, maybe (1) is better for now. We can switch to (2) if/when it's truly necessary.

By then, we might get ocaml-crunch upstreamed into Dune in some form, making (2) easy.

github-actions[bot] commented 4 years ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.