Documentation request: Explain documentation generation

[dunnl]

Version: Dune 2.4.0 Issue: I am confused about how to generate documentation Suggestion: Any of the following:

1. Explain that dune build @doc builds documentation for packages
2. Explain what command dune build @doc is running in the docs.
3. Print the command dune build @doc is using with --verbose
4. Retool dune init <option> such that dune build @doc works immediately
5. Exit with non-0 after dune build @doc fails to build anything.

Explanation: It's not clear to me from reading the documentation either here or here that dune build @doc would only generate documentation for "packages" and not, for example, the the setup I get by running dune init executable (after inserting comments.)

When I tried generating documentation for (the output of) dune init executable I got an exit code of 0 which I took to mean "the documentation was generated," which it wasn't. I thought I would run dune build @doc --verbose to see what odoc invocation was being used, but it doesn't say. Then I thought I would check the docs (linked above) to see what the command was, but it doesn't say.

Finally I figured out by trial and error that I need to make a "package."

I am new to OCaml, yes.

[ghost]

/cc @jonludlam who is our odoc expert

[jonludlam]

👍

[demoleee7]

I can help you with anything you need inbox me [email protected]