View Source examples-styler-ex

Use Styler on elixir code examples in your docs!

click to see build pipeline click to see build pipeline click to see build pipeline

Hex version Documentation

Styler.Examples is an extension for adobe/elixir-styler that styles code examples in your docstrings and markdown files!

usage

Usage

This package implements a mix format plugin. Add the following plugins value to your .formatter.exs file:

[
  plugins: [Styler.Examples.MultiPlugin],
  inputs: ...
]

Although it is also a plugin, Styler itself should not be added. mix format will only run one plugin per file, so if both Styler and Styler.Examples are present, only the one listed first will be run for .ex and .exs files. Styler.MultiPlugin handles running both Styler and Styler.Examples on those files in sequence.

Styler.Examples will also be run on any .md and .cheatmd files returned by your :input filters. Be sure to add your README of you want your examples styled!

what-gets-styled

What gets styled

We follow the same approach as ExUnit doc tests: example code must be prefaced by iex>.

iex> # Input
iex> 1 +     1
iex> # Output
iex> 1 + 1

Code found on contiguous lines is styled together:

iex> # Input
iex> def add(a, b),
iex>   do: a + b
iex> # Output
iex> def add(a, b), do: a + b

Any lines prefaced with iex> that are separated in any way will be styled separately.

approach-and-limitations

Approach and Limitations

This package is still in very early development; be sure to back up your code before running the formatter.

Our current approach simply finds any lines starting with iex> via regex and styles those. It ignores considerations of context, such code blocks or @doc attributes. Be warned that the formatter will execute on ANY lines that fit this criteria, like multi-line strings which start with iex>, for instance the inputs for our own test suite!

As a starting approach, we suspect this will be fine for the vast majority of projects. However, if it does cause issues for your particular code, please open a ticket with steps to re-create the issue and we'll take a look!

installation

Installation

If available in Hex, the package can be installed by adding examples_styler to your list of dependencies in mix.exs:

def deps do
  [
    {:examples_styler, "~> 0.1", only: [:dev, :test], runtime: false}
  ]
end