Dune: Warn when documenting an executable produces empty documentation

[Lelio-Brun]

When running dune build @doc in a project only containing a package consisting of an executable, odoc does not produce anything but almost empty index files.
dune build @doc-private does not produce anything at all.

It is maybe expected that non-library code does not need documentation pages, but it might be not that obvious.

MNWE:

• hello.ml

(** An Hello World program *)

(** The message *)
let msg = "Hello, World!"

(** The entry point *)
let main () = print_endline msg

let () = main ()

• dune

(executable
  (package ohello)
  (public_name hello)
  (name hello))

• empty ohello.opam

[rgrinberg]

Yeah, indeed it might be a bit unexpected. Perhaps odoc should be extended into documenting executables as well? @aantron @rizo ?

[aantron]

Something like this expected with how odoc is currently conceived, which is a tool for documenting OCaml/Reason APIs. Since an executable doesn't expose an API, there would typically be nothing to document. The executable's documentation would be in its man pages, --help output, etc., instead.

Of course, the actual HTML output produced by Dune+odoc for an executable might be messy right now. Maybe we need to avoid empty index files, or print a warning explaining why an empty file was generated, or why Dune wanted to generate an empty index, and what the rationale for that is.

And, of course, discussion of this reasoning is welcome :)

[Lelio-Brun]

I see, this makes sense.

I support the need for some kind of a warning.

[aantron]

@rgrinberg I can take care of this as my first proper Dune issue, though I need to work on some other things in odoc first.

[rgrinberg]

Can we make such a warning be displayed only in the dev profile? I think that when we build docs for packages in "production", we do it in bulk and we don't really care if a particular package has no docs.

[rizo]

I think it would actually be useful to have documentation for executables. Often I want to document a script I'm working on but creating a separate library feels unnecessary.

the actual HTML output produced by Dune+odoc for an executable might be messy right now

Do you have any particular examples of that?

For example, using the cmt file produced for the content presented by @Lelio-Brun generates the following docs:

Currently dune only supplies cmti files to odoc when compiling documentation:

https://github.com/ocaml/dune/blob/c3b32de8e374e33c1092190662e3a96101808808/src/odoc.ml#L134

Maybe for binaries it could use cmt files for executables? cmi don't seem to include docstrings in my tests.

Alternatively I think not generating docs for executables is better than generating empty output, even if there's a warning.