lint-doc check is a waste of energy

[talex5]

There's some discussion on https://discuss.ocaml.org/t/ocaml-org-recapping-2022-and-queries-on-the-fediverse/11099/22 about saving energy for the cluster.

I suggest removing the lint-doc stage. This is run for every single commit currently, and doesn't do anything (it runs with ODOC_WARN_ERROR=false which means that documentation errors don't fail the build).

Example: https://ci.ocamllabs.io:8100/job/2023-01-05/133221-ci-ocluster-build-c7323d

[MisterDA]

I agree. The current pipeline also reports (as expected) warnings with cross-refs because odoc can't find them unless the package is installed. There's also a misconception between opam's with-doc and Dune's (documentation …) stanza reported here ocaml/dune#6022. So altogether, the pipeline in its current form isn't too useful.

I am somewhat convinced that linting docs is still a good idea, people don't often run dune build @doc and fix the warnings generated. Maybe we could kill and resurrect that idea in some way elsewhere?

[tmcgilchrist]

I am somewhat convinced that linting docs is still a good idea, people don't often run dune build @doc and fix the warnings generated.

I'm in favour of making the linting docs stage work properly and then failing the build based on incorrect docs. We have 2 bugs #264 and #410 that would improve the usability of lint-doc. How can we fix the warnings with cross-refs? @jonludlam perhaps you could point us in the right direction?

[MisterDA]

To fix the cross-refs warning we have to install the opam package. Maybe we can trigger usual warnings while building and installing the docs this way.

[jonludlam]

I suspect we need two things:

1. For dune to grow the ability to build docs for pre-installed packages
2. For this process to distinguish between running odoc on pre-installed packages and local ones, so we only report errors on local source.

Point 2 is not perfect, because we expand functors from libraries and resolution problems in those expansions will appear to be local problems - this can be seen in expansions of Stdlib.Map.S which is commonly expanded and has resolution problems in many versions of the compiler.