# Extractly

It has been generated from the template `` by Extractly (
and any changes you make in this file will most likely be lost

[![Coverage Status](](

##  Mix task to Transform EEx templates in the context of the `Extractly` module.

  This tool serves two purposes.

  1. A simple CLI to basicly `EEx.eval_file/2`

  1. Access to the `Extractly` module (available as binding `xtra` too)

  1. Access to the name of the rendered template with the `template` binding

  The `Extractly` module gives easy access to Elixir metainformation of the application using
  the `extractly` package, notably, _module_  and _function_ documentation.

  This is BTW the raison d'être of this package, simple creation of a `` file with very simple
  access to the projects hex documentation.

  Thusly hexdoc and Github will always be synchronized.

  To see that in action just look at the [``]( file of this package and compare
  with what you are reading here.

  Example Template:

      Some text
      <%= xtra.functiondoc("M.shiny_function/2") %>
      <%= xtra.moduledoc("String") %>

      More text

### Usage:

    mix xtra [options]... [template]

#### Options:

    --help | -h     Prints short help information to stdout and exits.
    --quiet | -q    No output to stdout or stderr
    --version | -v  Prints the current version to stdout and exits.
    --verbose | -V  Prints additional output to stderr

    --output filename
              The name of the file the rendered template is written to, defaults to the templates'
              name, without the suffix `.eex`

#### Argument:

    template, filename of the `EEx` template to use, defaults to `""`

### API

### Extractly.moduledoc/2

  Returns docstring of a module


### Extractly.functiondoc/2

  Returns docstring of a function

      iex(0)> {:ok, lines} = Extractly.functiondoc("Extractly.moduledoc/2") |> hd()
      ...(0)> lines |> String.split("\n") |> Enum.take(3)
      ["  Returns docstring of a module", "  Ex:", ""]

  We can also pass a list of functions to get their docs concatenated

      iex(1)> [{:ok, moduledoc}, {:error, message}] = Extractly.functiondoc(["Extractly.moduledoc/2", "Extactly.functiondoc/2"])
      ...(1)> moduledoc |> String.split("\n") |> Enum.take(4)
      [ "  Returns docstring of a module",
        "  Ex:",
        "      Extractly.moduledoc(\"Extractly\")"]
      iex(2)> message
      "Function doc for function Extactly.functiondoc/2 not found"

  If all the functions are in the same module the following form can be used

      iex(3)> [{:ok, out}, _] = Extractly.functiondoc(["moduledoc/2", "functiondoc/2"], module: "Extractly")
      ...(3)> String.split(out, "\n") |> hd()
      "  Returns docstring of a module"

  However it is convenient to add a markdown headline before each functiondoc, especially in these cases,
  it can be done by indicating the `headline: level` option

      iex(4)> [{:ok, moduledoc}, {:ok, functiondoc}] = Extractly.functiondoc(["moduledoc/2", "functiondoc/2"], module: "Extractly", headline: 2)
      ...(4)> moduledoc |> String.split("\n") |> Enum.take(3)
      [ "## Extractly.moduledoc/2",
        "  Returns docstring of a module"]
      iex(5)> functiondoc |> String.split("\n") |> Enum.take(3)
      [ "## Extractly.functiondoc/2",
        "  Returns docstring of a function"]

  Often times we are interested by **all** public functiondocs...

      iex(6)> [{:ok, out}|_] = Extractly.functiondoc(:all, module: "Extractly", headline: 2)
      ...(6)> String.split(out, "\n") |> Enum.take(3)
      [ "## Extractly.do_not_edit_warning/1",
        "  Emits a comment including a message not to edit the created file, as it will be recreated from this template."]

  We can specify a language to wrap indented code blocks into ` ```elixir\n...\n``` `

  Here is an example

      iex(7)> [ok: doc] = Extractly.functiondoc("Extractly.functiondoc/2", wrap_code_blocks: "elixir")
      ...(7)> doc |> String.split("\n") |> Enum.take(10)
      [ "  Returns docstring of a function",
        "  Ex:",
        "      iex(0)> {:ok, lines} = Extractly.functiondoc(\"Extractly.moduledoc/2\") |> hd()",
        "      ...(0)> lines |> String.split(\"\\n\") |> Enum.take(3)",
        "      [\"  Returns docstring of a module\", \"  Ex:\", \"\"]",
        "  We can also pass a list of functions to get their docs concatenated"]

### Extractly.macrodoc/2

  Returns docstring of a macro

  Same naming convention for macros as for functions.

### Extractly.task/2

Returns the output of a mix task

    iex(8)> Extractly.task("cmd", ~W[echo 42])

    iex(9)> try do
    ...(9)>   Extractly.task("xxx")
    ...(9)> rescue
    ...(9)>   e in RuntimeError -> e.message |> String.split("\n") |> hd()
    ...(9)> end
    "The following output was produced wih error code 1"

## Installation

If [available in Hex](, the package can be installed
by adding `extractly` to your list of dependencies in `mix.exs`:

def deps do
    {:extractly, "~> 0.5.0"}

Documentation can be generated with [ExDoc](
and published on [HexDocs]( Once published, the docs can
be found at [](

## Author

Copyright © 20[18-21] Robert Dober,,


Same as Elixir, which is Apache License v2.0. Please refer to [LICENSE](LICENSE) for details.

SPDX-License-Identifier: Apache-2.0