Builds the documentation with mix docs and fails on any ExDoc warning.

ExDoc warns about real defects a reader will hit - a reference to a function that does not exist, a moduledoc link that resolves nowhere, an undefined anchor - and a plain mix docs exits 0 anyway. Warnings that fail no build accumulate, so this stage is the ratchet: a project that reaches zero warnings stays there.

✓ Docs: No warnings (2.1s)
✗ Docs: 3 warnings (1.9s)

Each warning becomes a finding at the file:line ExDoc reports:

lib/my_app/user.ex
  42  [error] documentation references function MyApp.User.fetch/2 but it is undefined or private (ex_doc)

Both shapes ExDoc prints a warning in are read: the Elixir 1.18 diagnostic, an indented warning: line whose location closes the block on a └─ file:line: line, and the older form, a warning: line at the start of the line followed by an indented file:line: line. A warning ExDoc reports without a location falls back to the tool's output verbatim, so a warning is never hidden behind a parse.

Opt-in

Unlike the other tool-backed stages this one is off by default, even when :ex_doc is installed. Nearly every published package depends on :ex_doc to build its docs, so enabling on detection would turn currently-green gates red on upgrade, and this project does not move anyone's gate by default. Enable it in .quality.exs:

docs: [enabled: :auto]   # on when :ex_doc is installed (recommended)
docs: [enabled: true]    # forced; errors if :ex_doc is missing

With enabled: :auto a project without :ex_doc reports the stage as skipped (:ex_doc not installed), the way doctor and sobelow do.

What it builds

mix docs --formatter html --output <tmp dir> --warnings-as-errors: one formatter, because the epub build repeats the html build's warnings, and a temporary output directory that is deleted after the run, because a checker that leaves a doc/ tree behind has written to the repository. The project's own mix docs output is untouched.

--warnings-as-errors makes ExDoc 0.36 and later exit non-zero when it warned, which backs the parse: a warning printed in a shape the stage does not read still fails the stage, as ExDoc reported warnings (see output), instead of passing as No warnings. Earlier ExDoc versions accept the flag and ignore it, so there the parse alone decides.