# `ExQuality.Stages.Docs`
[🔗](https://github.com/riddler/ex_quality/blob/v0.16.0/lib/ex_quality/stages/docs.ex#L1)

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.

# `run`

```elixir
@spec run(keyword()) :: ExQuality.Stage.result()
```

Runs the docs stage.

## Config options

- `enabled` - `false` (default) | `:auto` (on when `:ex_doc` is installed) |
  `true` (forced)

---

*Consult [api-reference.md](api-reference.md) for complete listing*