Unable to make assets (images) work

[gadmm]

I have read with interest the documentation on the new feature of incorporating assets (e.g. images)

• https://ocaml.org/p/odoc/3.1.0/doc/odoc_for_authors.html#media (plus the bit about installing files with dune: https://ocaml.org/p/odoc/3.1.0/doc/odoc_for_authors.html#quickstart)
• Bigger documentation: https://github.com/ocaml/odoc/discussions/1113

I am sorry to report that I was unable to make it work in any possible combination and any possible interpretation of the documentation.

Here is what my attempt looks like:

/tmp/odoc-example/asset-example/doc$ ls
dune  image.png  index.mld
/tmp/odoc-example/asset-example/doc$ cat index.mld 
{0 heading}

Example text

{{image!image.png}Alt text}

/tmp/odoc-example/asset-example/doc$ cat dune 
(documentation)
(install
  (section doc)
  (files (image.png as odoc-pages/image.png)))
/tmp/odoc-example/asset-example/doc$ cd ..
/tmp/odoc-example/asset-example$ dune build @doc
File "../../../../doc/index.mld", line 5, characters 0-27:
Warning: Failed to resolve reference ./image.png Path 'image.png' not found
/tmp/odoc-example/asset-example$ odoc --version
3.1.0

At this point I have no clue what might be wrong and what I might have missed from the documentation. Do you see any obvious problem with my attempt? Or maybe could you please share a minimal working example from which I will investigate further?

[jonludlam]

The dune rules haven't yet been updated for odoc 3. Try using odoc_driver - you can either install the package and run odoc_driver <package name> or you can run it from within your dev dir - run dune build @install then dune exec -- odoc_driver <package name>. There's some more info here

[gadmm]

Thanks, I understand better: the problem is that I was using dune and I did not try more direct ways to invoke odoc. My bug report is therefore with the documentation, as it gives the impression that it was going to work with dune build @doc.

With regards to your suggestion of using odoc_driver, if I understand correctly https://ocaml.org/p/odoc/3.1.0/doc/odoc_for_authors.html#getting_started this is what ocaml.org uses, so if I switch myself to using it, then the documentation will appear as I expect on the website, is this correct?

One last question if I may; it is easy to setup the opam file to generate documentation with dune build @doc. Do you have an example of an opam configuation file that uses odoc_driver instead?

As to the bug report it would be very useful to have in each feature the minimal requirements for the three methods (odoc_driver, dune, odig), when relevant.

[gadmm]

With regards to your suggestion of using odoc_driver, if I understand correctly https://ocaml.org/p/odoc/3.1.0/doc/odoc_for_authors.html#getting_started this is what ocaml.org uses, so if I switch myself to using it, then the documentation will appear as I expect on the website, is this correct?

To answer my own question, I switched to using odoc_driver and the documentation on ocaml.org is now consistent with the one on my own website (besides another bug reported separately).

So I believe that this is simply a matter of documenting that assets do not work with dune currently.