- Extractly
- Extractly
- Extractly.do_not_edit_warning/1
- Extractly.functiondoc/2
- Extractly.macrodoc/2
- Extractly.moduledoc/2
- Extractly.task/2
- Extractly.toc/2
- Extractly.version/0
- Extractly.Toc
- Extractly.Toc.render/2
- Mix.Tasks.Xtra
- Mix task to Transform EEx templates in the context of the
Extractly
module. - Mix.Tasks.Xtra.Help
- Author
- LICENSE
Provide easy access to information inside the templates rendered by mix xtra
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 %>
Returns docstring of a function Ex:
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
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
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"]
...(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...
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
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"]
Returns docstring of a macro
Returns docstring of a module
E.g. verbatim
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
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
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"
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"
]
Returns the output of a mix task Ex:
iex(14)> Extractly.task("cmd", ~W[echo 42])
"42\n"
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"
Extract Table Of Contents from a markdown document
The files used for the following doctest can be found here
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
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
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
A convenience method to access this libraries version
Extract Table Of Contents from a list of lines representing a Markdown document
Depending on the options the Table Of Contents extracted from the lines can be rendered in different formats, the default being Markdown
iex(1)> render(["# Hello", "## World"])
["- Hello", " - World"]
Numbered lists can be created too
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
iex(3)> render(["### Alpha", "ignored", "##### Alpha.1", "", "### Beta"])
["- Alpha", " - Alpha.1", "- Beta"]
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
iex(4)> render(["# First", "### Third (but will go to second level)", "## Second"], remove_gaps: true)
["- First", " - Third (but will go to second level)", " - Second"]
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
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)",
]
Sometimes it might be appropriate to generate HTML directly
iex(6)> render(["## One", "### Two"], format: :html)
["<ul>", "<li>One<ul>", "<li>Two</li>", "</ul></li>", "</ul>"]
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
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>},
]
Either a linear PushList
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]
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)"]]]
iex(9)> render(["# Does not really matter"], format: :unknown)
{:error, "Unsupported format: unknown in render"}
This tool serves two purposes.
-
A simple CLI to basicly
EEx.eval_file/2
-
Access to the
Extractly
module (available as bindingxtra
too) -
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
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 xtra [options]... [template]
--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`
template, filename of the `EEx` template to use, defaults to `"README.md.eex"`
Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/extractly.
Copyright © 20[18-21] Robert Dober, robert.dober@gmail.com,
Same as Elixir, which is Apache License v2.0. Please refer to LICENSE for details.