odoc icon indicating copy to clipboard operation
odoc copied to clipboard

Support for package documentation assets

Open dbuenzli opened this issue 8 years ago • 3 comments

In https://github.com/dbuenzli/odig/commit/90f8660f2b386f0707ea4148778bf31cf6d50050 I have implemented a first shot at support for documentation assets (used by Vg since this commit https://github.com/dbuenzli/vg/commit/e01ae8eb6214725c8aae0a3fd5a001787fc89782) .

I do however think that odig is the wrong place to standardize this and that the scheme should be in odoc (since without support in the ocamldoc language it influences the links you make in your docs) and be simply driven by odig. As we discussed in https://github.com/dbuenzli/odig/issues/6, unless something happens quickly at the ocamldoc level I think we should go for something straightforward, usable now.

One idea would be to simply allow to do what odig does at the moment by adding an --assets-dir DIR option to the html command whose semantics is to simply copy over whatever is in DIR in an _assets directory at the root of the package HTML after having generated the HTML. However though that may be a bit build system unfriendly, an odoc asset --pkg PKG file that copies file over to _assets would be more.

Alternatively we could do nothing until there is support in the ocamldoc language/odoc and rely on odig's scheme meanwhile.

dbuenzli avatar Jan 11 '17 11:01 dbuenzli

This issue becomes more acute now that we have the manuals (#61).

dbuenzli avatar Oct 25 '17 14:10 dbuenzli

Ping.

I've just hit this, as I was thinking about how a merlin manual (currently being written) might render on the new v3.ocaml.org It seems pretty important to have this.

trefis avatar Jan 18 '22 16:01 trefis

(And indeed https://v3.ocaml.org/p/vg/0.9.4/doc/Vg/index.html#paths vs https://erratique.ch/software/vg/doc/Vg/index.html#paths )

trefis avatar Jan 18 '22 17:01 trefis