odoc 2.3.0 gives "Rule failed to generate the following targets"

[talex5]

After upgrading to odoc 2.3.0, I get this error building Eio:

$ dune build @doc
File "_doc/_html/eio/Eio__core/_unknown_", line 1, characters 0-0:
Error: Rule failed to generate the following targets:
- _doc/_html/eio/Eio__core/index.html

Any idea what could cause that?

The problem also appears in CI (e.g. https://ocaml.ci.dev/github/ocaml-multicore/eio/commit/4db6533fa661ef348ae3197cc6c465622ae02703/variant/%28lint-doc%29#L429-432)

/src: (run (shell "ODOC_WARN_ERROR=false opam exec -- dune build @doc || (echo \"dune build @doc failed\"; exit 2)"))
File "_doc/_html/eio/Eio__core/_unknown_", line 1, characters 0-0:
Error: Rule failed to generate the following targets:
- _doc/_html/eio/Eio__core/index.html

[jonludlam]

hum interesting, why was dune trying to build Eio__core/index.html - that's a hidden module :-(

[jonludlam]

Ah, because you've got an explicit module called Eio__core. Hum. Why do you need the double underscore? Odoc treats that specially to mean the module should be hidden.

[jonludlam]

Oh, I see - it should be hidden - the top of eio_core.mli:

(** Private internal module. Use {!Eio} instead. *)

(** @canonical Eio.Switch *)
module Switch : sig
  (** Many resources in Eio (such as fibers and file handles) require a switch to

[talex5]

Yep. I'm happy for it to be hidden in the docs. Its contents get included at the start of eio.ml, so people don't refer to it directly. Previously, odoc included it in the docs (e.g. https://ocaml-multicore.github.io/eio/eio/index.html), but it would be better to hide it.

[panglesd]

Small recap of this issue:

• Previously, odoc would generate an empty html file for hidden compilation units
• Since Render source code along side documentation #909 (more precisely this modification), odoc no longer does that. The idea was that odoc html-generate needs to be called on hidden modules to generate the source code rendering, and we don't want all those empty html files.
• However, it seems that dune rules for building documentation are such that any file in the source tree has to produce an html file. That is why dune is now complaining.

We have to decide whether we want to revert to the previous behavior, or open an issue in dune. I'm not sure yet (there might be some more changes in the way source code rendering is built, and we might want to wait for that before deciding?).

[Julow]

This should be fixed by #1069, which is being released.