# Extractly
<!--
DO NOT EDIT THIS FILE
It has been generated from the template `README.md.eex` by Extractly (https://github.com/RobertDober/extractly.git)
and any changes you make in this file will most likely be lost
-->
[](https://github.com/RobertDober/extractly/actions/workflows/ci.yml)
[](https://coveralls.io/github/RobertDober/extractly?branch=master)
[](https://hex.pm/packages/extractly)
[](https://hex.pm/packages/extractly)
[](https://hex.pm/packages/extractly)
## 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 `README.md` 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 [`README.md.eex`](README.md.eex) 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 `"README.md.eex"`
### API
### Extractly.moduledoc/2
Returns docstring of a module
Ex:
Extractly.moduledoc("Extractly")
### Extractly.functiondoc/2
Returns docstring of a function
Ex:
```elixir
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
```elixir
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
```elixir
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
```elixir
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...
```elixir
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
```elixir
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:",
"",
"```elixir",
" 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
Ex:
```elixir
iex(8)> Extractly.task("cmd", ~W[echo 42])
"42\n"
```
```elixir
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](https://hex.pm/docs/publish), the package can be installed
by adding `extractly` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:extractly, "~> 0.5.0"}
]
end
```
Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/extractly](https://hexdocs.pm/extractly).
## Author
Copyright © 20[18-21] Robert Dober, robert.dober@gmail.com,
# LICENSE
Same as Elixir, which is Apache License v2.0. Please refer to [LICENSE](LICENSE) for details.
SPDX-License-Identifier: Apache-2.0
