# 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)
- [Extractly](#extractly)
- [Extractly](#extractly)
- [Extractly.do_not_edit_warning/1](#extractlydo_not_edit_warning1)
- [Extractly.functiondoc/2](#extractlyfunctiondoc2)
- [Extractly.macrodoc/2](#extractlymacrodoc2)
- [Extractly.moduledoc/2](#extractlymoduledoc2)
- [Extractly.task/2](#extractlytask2)
- [Extractly.toc/2](#extractlytoc2)
- [Extractly.version/0](#extractlyversion0)
- [Extractly.Toc](#extractlytoc)
- [Extractly.Toc.render/2](#extractlytocrender2)
- [Mix.Tasks.Xtra](#mixtasksxtra)
- [Mix task to Transform EEx templates in the context of the `Extractly` module.](#mix-task-to-transform-eex-templates-in-the-context-of-the-extractly-module)
- [Mix.Tasks.Xtra.Help](#mixtasksxtrahelp)
- [Usage:](#usage)
- [Author](#author)
- [LICENSE](#license)
## Extractly
Provide easy access to information inside the templates rendered by `mix xtra`
## 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.
It is a convenience to include this into your templates as follows
<%= xtra.do_not_edit_warning %>
or I18n'ed
<%= xtra.do_not_edit_warning, lang: :fr %>
If you are not generating html or markdown the comment can be parametrized
<%= xtra.do_not_edit_warning, comment_start: "-- ", comment_end: "" %>
If you want to include the name of the source template use `template: template` option, so
a call may be as complex as:
<%= xtra.do_not_edit_warning, comment_start: "-- ", comment_end: "", template: template, lang: :it %>
## Extractly.functiondoc/2
Returns docstring of a function
Ex:
```elixir
iex(1)> {:ok, lines} = Extractly.functiondoc("Extractly.moduledoc/2") |> hd()
...(1)> lines |> String.split("\n") |> Enum.take(3)
[" Returns docstring of a module", "", " E.g. verbatim"]
```
We can also pass a list of functions to get their docs concatenated
```elixir
iex(2)> [{:ok, moduledoc}, {:error, message}] = Extractly.functiondoc(["Extractly.moduledoc/2", "Extactly.functiondoc/2"])
...(2)> moduledoc |> String.split("\n") |> Enum.take(4)
[ " Returns docstring of a module",
" E.g. verbatim",
"",
" Extractly.moduledoc(\"Extractly\")"]
...(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"]
...(4)> 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(5)> [{:ok, out}|_] = Extractly.functiondoc(:all, module: "Extractly", headline: 2)
...(5)> 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(6)> [ok: doc] = Extractly.functiondoc("Extractly.functiondoc/2", wrap_code_blocks: "elixir")
...(6)> doc |> String.split("\n") |> Enum.take(10)
[ " Returns docstring of a function",
" Ex:",
"",
"```elixir",
" iex(1)> {:ok, lines} = Extractly.functiondoc(\"Extractly.moduledoc/2\") |> hd()",
" ...(1)> lines |> String.split(\"\\n\") |> Enum.take(3)",
" [\" Returns docstring of a module\", \"\", \" E.g. verbatim\"]",
"```",
"",
" We can also pass a list of functions to get their docs concatenated"]
```
## Extractly.macrodoc/2
Returns docstring of a macro
## Extractly.moduledoc/2
Returns docstring of a module
E.g. verbatim
```elixir
iex(7)> {:ok, doc} = Extractly.moduledoc("Extractly")
...(7)> doc
" Provide easy access to information inside the templates rendered by `mix xtra`\n"
```
We can use the same options as with `functiondoc`
```elixir
iex(8)> {:ok, doc} = Extractly.moduledoc("Extractly", headline: 2)
...(8)> doc |> String.split("\n") |> Enum.take(3)
[
"## Extractly", "", " Provide easy access to information inside the templates rendered by `mix xtra`"
]
```
If we also want to use `functiondoc :all, module: "Extractly"` **after** the call of `moduledoc` we can
include `:all` in the call of `moduledoc`, which will include function and macro docstrings as well
```elixir
iex(9)> [{:ok, moduledoc} | _] =
...(9)> moduledoc("Extractly", headline: 3, include: :all)
...(9)> moduledoc
"### Extractly\n\n Provide easy access to information inside the templates rendered by `mix xtra`\n"
```
```elixir
iex(10)> [_, {:ok, first_functiondoc} | _] =
...(10)> moduledoc("Extractly", headline: 3, include: :all)
...(10)> first_functiondoc |> String.split("\n") |> Enum.take(5)
[
"### 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.",
"",
" It is a convenience to include this into your templates as follows"
]
```
## Extractly.task/2
Returns the output of a mix task
Ex:
```elixir
iex(14)> Extractly.task("cmd", ~W[echo 42])
"42\n"
```
```elixir
iex(15)> try do
...(15)> Extractly.task("xxx")
...(15)> rescue
...(15)> e in RuntimeError -> e.message |> String.split("\n") |> hd()
...(15)> end
"The following output was produced wih error code 1"
```
## Extractly.toc/2
Extract Table Of Contents from a markdown document
The files used for the following doctest can be found [here](https://github.com/RobertDober/extractly/tree/master/test/fixtures)
```elixir
iex(11)> lines = [
...(11)> "## Usage",
...(11)> "### API",
...(11)> "#### EarmarkParser.as_ast/2",
...(11)> "### Support",
...(11)> ]
...(11)> toc(lines, gh_links: true)
{:ok, [
"- [Usage](#usage)",
" - [API](#api)",
" - [EarmarkParser.as_ast/2](#earmarkparseras_ast2)",
" - [Support](#support)",
]}
```
But if you do not want links
```elixir
iex(12)> lines = [
...(12)> "## Usage",
...(12)> "### API",
...(12)> "#### EarmarkParser.as_ast/2",
...(12)> "### Support",
...(12)> ]
...(12)> toc(lines)
{:ok, [
"- Usage",
" - API",
" - EarmarkParser.as_ast/2",
" - Support",
]}
```
In case of bad options an error tuple is returned (no utf8 encoded
input should ever result in an error_tuple
```elixir
iex(13)> lines = [] # options are checked even if input is empty
...(13)> toc(lines, no_such_option: "x")
{:error, "Unsupported option no_such_option"}
```
A more detailed description can be found in `Extractly.Toc`'s docstrings
## Extractly.version/0
A convenience method to access this libraries version
## Extractly.Toc
Extract Table Of Contents from a list of lines representing a Markdown document
## Extractly.Toc.render/2
Depending on the options the Table Of Contents extracted from the lines can be
rendered in different formats, the default being Markdown
#### Markdown
```elixir
iex(1)> render(["# Hello", "## World"])
["- Hello", " - World"]
```
Numbered lists can be created too
```elixir
iex(2)> render(["# Hello", "## World"], type: :ol)
["1. Hello", " 1. World"]
```
Oftentimes the level of headlines is adapted for output, e.g. `###` for the top
and `#####` for the second level.
`render` accounts for that
```elixir
iex(3)> render(["### Alpha", "ignored", "##### Alpha.1", "", "### Beta"])
["- Alpha", " - Alpha.1", "- Beta"]
```
##### Remove Gaps
Sometimes there will be _gaps_ in the levels of headlines and these holes might
not reflect semantic but rather stylistic concerns, if this is the case the option
`remove_gaps` can be set to `true`
```elixir
iex(4)> render(["# First", "### Third (but will go to second level)", "## Second"], remove_gaps: true)
["- First", " - Third (but will go to second level)", " - Second"]
```
##### Github README Links
This is all nice, however a TOC is most useful if links are provided.
`render` can render Github like links to within the page, here is a real world example
from a Github README.md file
```elixir
iex(5)> lines = [
...(5)> "## Usage",
...(5)> "### API",
...(5)> "#### EarmarkParser.as_ast/2",
...(5)> "### Support",
...(5)> ]
...(5)> render(lines, gh_links: true)
[
"- [Usage](#usage)",
" - [API](#api)",
" - [EarmarkParser.as_ast/2](#earmarkparseras_ast2)",
" - [Support](#support)",
]
```
#### HTML
Sometimes it might be appropriate to generate HTML directly
```elixir
iex(6)> render(["## One", "### Two"], format: :html)
["<ul>", "<li>One<ul>", "<li>Two</li>", "</ul></li>", "</ul>"]
```
##### Exlcuding levels and changing list styles
Let us examine these two options with HTML output, they work too for Markdown of course, but are meaningless with the more
_raw_ output formats
So we do not want to include levels greater than, say 3, and we also want to ignore top level headlines, probably because only
one top level part has sublevels
```elixir
iex(7)> document = [
...(7)> "# Ignore",
...(7)> "# Too, but not what's below",
...(7)> "## Synopsis",
...(7)> "## Description",
...(7)> "### API",
...(7)> "#### too detailed",
...(7)> "### Tips & Tricks",
...(7)> "# Ignored again"
...(7)> ]
...(7)> render(document, format: :html, min_level: 2, max_level: 3, start: 5, type: :ol)
[
~S{<ol start="5">},
~S{<li>Synopsis</li>},
~S{<li>Description<ol>},
~S{<li>API</li>},
~S{<li>Tips & Tricks</li>},
~S{</ol></li>},
~S{</ol>},
]
```
#### PushList
Either a linear `PushList`
```elixir
iex(8)> render(["# I", "## I.1", "## I.2", "### I.2.(i)", "# II", "### II.1.(ii)"], format: :push_list)
["I", :open, "I.1", "I.2", :open, "I.2.(i)", :close, :close, "II", :open, :open, "II.1.(ii)", :close, :close]
```
#### AST tree
```elixir
iex(9)> render(["# I", "## I.1", "## I.2", "### I.2.(i)", "# II", "### II.1.(ii)"], format: :ast)
["I", ["I.1", "I.2", ["I.2.(i)"]], "II", [["II.1.(ii)"]]]
```
#### Unsupported Formats
```elixir
iex(9)> render(["# Does not really matter"], format: :unknown)
{:error, "Unsupported format: unknown in render"}
```
## Mix.Tasks.Xtra
## 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") %>
<%= xtra.moduledoc("MyModule", include: :all) %>
<%= xtra.toc "SomeFile.md" %>
More text
A special case is the occurrence of `<%= xtra.toc :self, ... %>` which just inserts a
placeholder which than is replaced by the TOC of the generated output in a second pass
## Mix.Tasks.Xtra.Help
### 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"`
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 -->
