Command to extract errors from odocl files

[lpw25]

Currently problems, such as unresolved references, are reported as warnings when building documentation. Unfortunately, warnings just get lost in people's build logs and never seen. We can convert them to errors, but that prevents you from building the docs to see where the problem is.

I would like a command that would give me a list of issues when given an .odocl file. (I can't remember if these files exist yet, but I mean the files that represent a module after linking but before generating html).

At the moment I am using a hacked up python script that read's the html to do this. It is very useful for finding issues, but a proper command would be much better.

[lubegasimon]

IIUC, we wouldn’t expect to have unresolved references after linking/generating .odocl files.

[Octachron]

Errors happen, and I agree with @lpw25 that it would be interesting to get a clear error report while still building the documentation. Typically, building the standard library documentation requires to tolerate a handful of unresolved references, because ocamldoc and odoc does not agree on how to link mld files. I would be interested in a way to monitor that no other errors creep in the documentation.

[jonludlam]

We generate warnings when we can't resolve paths, and there's an option to turn those warnings into errors. We don't do the same for references right now as unresolved references don't necessarily end up in the output - the document layer will replace them, which is why we're emitting the warnings when we actually end up rendering unresolved links in the html. I think the places where this happens are a little ad-hoc at the moment, and could do with formalising, at which point it'll be easier to point them out earlier - either at the point we generate the odocl or as a post-processing step on the generated file. We could even then turn on warnings-as-errors and break builds when we notice them. Some projects will be able to do this sooner than others, I imagine :-)