# `ExQuality.Stages.Docs`
[🔗](https://github.com/riddler/ex_quality/blob/v0.15.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 `mix docs` exits 0 anyway on most versions. 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)

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>`: 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.

# `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*