After I gave a lighting talk about my previous formatter plugin, Markdown Code Block Formatter, a person from the audience (hi Tobi!) asked me whether they could use it to format doctests. The answers was no… so I wrote another plugin that could do it!

It’s called Doctest Formatter. Check out its documentation on HexDocs and its source on GitHub.

#Installation

The package can be installed by adding doctest_formatter to your list of dependencies in mix.exs:

def deps do
  [
    {:doctest_formatter, "~> 0.2.0", runtime: false}
  ]
end

Then, extend your .formatter.exs config file by adding the plugin.

# .formatter.exs
[
  plugins: [DoctestFormatter],
  inputs: [
    # your usual inputs ...
  ]
]

Elixir 1.13.2 or up is required. Versions lower than 1.13 do not support formatter plugins, and versions 1.13.0 and 1.13.1 do not support formatter plugins for .ex files.

#Usage

Run mix format. Now, this command will not only format your .ex files but also the Elixir code in your doctests, inside your @doc and @moduledoc attributes.

In addition to formatting the Elixir code, it will also format your iex> prompts. Every iex> prompt that is not the first line of the test, will get changed to ...>. This is not strictly necessary, but it’s recommended in the docs.

It should work for every possible valid syntax of doctests, as long as it’s a static value (see known limitations). Please open an issue if you find any bugs.

Running mix format in the terminal formats doctests inside @doc and @moduledoc attributes
The formatter in action.