View Source examples-styler-ex
Use Styler on elixir code examples in your docs!
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