From b8fbc672e76317f796edb915ca32807d6fda0a7f Mon Sep 17 00:00:00 2001 From: Zach Daniel Date: Tue, 26 Sep 2023 23:23:55 -0400 Subject: [PATCH] docs: update hexdocs with new spark dsl tools (#59) --- documentation/dsls/DSL:-Reactor.cheatmd | 1062 +++++++++++++++++++++++ lib/reactor.ex | 14 - lib/reactor/dsl/argument.ex | 10 +- lib/reactor/dsl/around.ex | 6 +- lib/reactor/dsl/collect.ex | 7 +- lib/reactor/dsl/compose.ex | 5 +- lib/reactor/dsl/group.ex | 10 +- lib/reactor/dsl/input.ex | 7 +- lib/reactor/dsl/step.ex | 33 +- lib/reactor/dsl/switch.ex | 4 +- mix.exs | 36 +- mix.lock | 4 +- 12 files changed, 1100 insertions(+), 98 deletions(-) create mode 100644 documentation/dsls/DSL:-Reactor.cheatmd diff --git a/documentation/dsls/DSL:-Reactor.cheatmd b/documentation/dsls/DSL:-Reactor.cheatmd new file mode 100644 index 0000000..aa6792c --- /dev/null +++ b/documentation/dsls/DSL:-Reactor.cheatmd @@ -0,0 +1,1062 @@ +# DSL: Reactor.Dsl + + + +## reactor +The top-level reactor DSL + +### Nested DSLs + * [around](#reactor-around) + * argument + * wait_for + * [collect](#reactor-collect) + * argument + * wait_for + * [compose](#reactor-compose) + * argument + * wait_for + * [debug](#reactor-debug) + * argument + * wait_for + * [group](#reactor-group) + * argument + * wait_for + * [input](#reactor-input) + * [step](#reactor-step) + * argument + * wait_for + * [switch](#reactor-switch) + * matches? + + * default + + + + + + +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `return` | `atom` | | Specify which step result to return upon completion. | + + + +## reactor.around +```elixir +around name, fun \ nil +``` + + +Wrap a function around a group of steps. + + +### Nested DSLs + * [argument](#reactor-around-argument) + * [wait_for](#reactor-around-wait_for) + + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | A unique name of the group of steps. | +| `fun`* | `(any, any, any, any -> any) \| mfa` | | The around function. See `Reactor.Step.Around` for more information. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `allow_async?` | `boolean` | `false` | Whether the emitted steps should be allowed to run asynchronously. | + + +## reactor.around.argument +```elixir +argument name, source \ nil +``` + + +Specifies an argument to a Reactor step. + +Each argument is a value which is either the result of another step, or an input value. + +Individual arguments can be transformed with an arbitrary function before +being passed to any steps. + + + + +### Examples +``` +argument :name, input(:name) + +``` + +``` +argument :year, input(:date, [:year]) + +``` + +``` +argument :user, result(:create_user) + +``` + +``` +argument :user_id, result(:create_user) do + transform & &1.id +end + +``` + +``` +argument :user_id, result(:create_user, [:id]) + +``` + +``` +argument :three, value(3) + +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | The name of the argument which will be used as the key in the `arguments` map passed to the implementation. | +| `source`* | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` | | What to use as the source of the argument. See `Reactor.Dsl.Argument` for more information. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `transform` | `(any -> any) \| module \| nil` | | An optional transformation function which can be used to modify the argument before it is passed to the step. | + + + + + +### Introspection + +Target: `Reactor.Dsl.Argument` + +## reactor.around.wait_for +```elixir +wait_for names +``` + + +Wait for the named step to complete before allowing this one to start. + +Desugars to `argument :_, result(step_to_wait_for)` + + + + +### Examples +``` +wait_for :create_user +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `names`* | `list(atom) \| atom` | | The name of the step to wait for. | + + + + + + +### Introspection + +Target: `Reactor.Dsl.WaitFor` + + + + +### Introspection + +Target: `Reactor.Dsl.Around` + +## reactor.collect +```elixir +collect name +``` + + +A Reactor step which simply collects and returns it's arguments. + +Arguments can optionally be transformed before returning. + + +### Nested DSLs + * [argument](#reactor-collect-argument) + * [wait_for](#reactor-collect-wait_for) + + +### Examples +``` +collect :latest_release_uri do + argument :repository, input(:repository) + argument :organisation, input(:organisation) + + transform fn inputs -> + %{uri: "https://api.github.com/repos/#{inputs.organisation}/#{inputs.repository}/releases/latest"} + end +end + +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | A unique name for the step. Used when choosing the return value of the Reactor and for arguments into other steps. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `transform` | `(any -> any) \| module \| nil` | | An optional transformation function which can be used to modify the entire argument map before it is returned. | + + +## reactor.collect.argument +```elixir +argument name, source \ nil +``` + + +Specifies an argument to a Reactor step. + +Each argument is a value which is either the result of another step, or an input value. + +Individual arguments can be transformed with an arbitrary function before +being passed to any steps. + + + + +### Examples +``` +argument :name, input(:name) + +``` + +``` +argument :year, input(:date, [:year]) + +``` + +``` +argument :user, result(:create_user) + +``` + +``` +argument :user_id, result(:create_user) do + transform & &1.id +end + +``` + +``` +argument :user_id, result(:create_user, [:id]) + +``` + +``` +argument :three, value(3) + +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | The name of the argument which will be used as the key in the `arguments` map passed to the implementation. | +| `source`* | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` | | What to use as the source of the argument. See `Reactor.Dsl.Argument` for more information. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `transform` | `(any -> any) \| module \| nil` | | An optional transformation function which can be used to modify the argument before it is passed to the step. | + + + + + +### Introspection + +Target: `Reactor.Dsl.Argument` + +## reactor.collect.wait_for +```elixir +wait_for names +``` + + +Wait for the named step to complete before allowing this one to start. + +Desugars to `argument :_, result(step_to_wait_for)` + + + + +### Examples +``` +wait_for :create_user +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `names`* | `list(atom) \| atom` | | The name of the step to wait for. | + + + + + + +### Introspection + +Target: `Reactor.Dsl.WaitFor` + + + + +### Introspection + +Target: `Reactor.Dsl.Collect` + +## reactor.compose +```elixir +compose name, reactor +``` + + +Compose another Reactor into this one. + +Allows place another Reactor into this one as if it were a single step. + + +### Nested DSLs + * [argument](#reactor-compose-argument) + * [wait_for](#reactor-compose-wait_for) + + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | A unique name for the step. Allows the result of the composed reactor to be depended upon by steps in this reactor. | +| `reactor`* | `Reactor \| module` | | The reactor module or struct to compose upon. | + + + +## reactor.compose.argument +```elixir +argument name, source \ nil +``` + + +Specifies an argument to a Reactor step. + +Each argument is a value which is either the result of another step, or an input value. + +Individual arguments can be transformed with an arbitrary function before +being passed to any steps. + + + + +### Examples +``` +argument :name, input(:name) + +``` + +``` +argument :year, input(:date, [:year]) + +``` + +``` +argument :user, result(:create_user) + +``` + +``` +argument :user_id, result(:create_user) do + transform & &1.id +end + +``` + +``` +argument :user_id, result(:create_user, [:id]) + +``` + +``` +argument :three, value(3) + +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | The name of the argument which will be used as the key in the `arguments` map passed to the implementation. | +| `source`* | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` | | What to use as the source of the argument. See `Reactor.Dsl.Argument` for more information. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `transform` | `(any -> any) \| module \| nil` | | An optional transformation function which can be used to modify the argument before it is passed to the step. | + + + + + +### Introspection + +Target: `Reactor.Dsl.Argument` + +## reactor.compose.wait_for +```elixir +wait_for names +``` + + +Wait for the named step to complete before allowing this one to start. + +Desugars to `argument :_, result(step_to_wait_for)` + + + + +### Examples +``` +wait_for :create_user +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `names`* | `list(atom) \| atom` | | The name of the step to wait for. | + + + + + + +### Introspection + +Target: `Reactor.Dsl.WaitFor` + + + + +### Introspection + +Target: `Reactor.Dsl.Compose` + +## reactor.debug +```elixir +debug name +``` + + +Inserts a step which will send debug information to the `Logger`. + + +### Nested DSLs + * [argument](#reactor-debug-argument) + * [wait_for](#reactor-debug-wait_for) + + +### Examples +``` +debug :debug do + argument :suss, result(:suss_step) +end + +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | A unique identifier for the step. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `level` | `:emergency \| :alert \| :critical \| :error \| :warning \| :notice \| :info \| :debug` | `:debug` | The log level to send the debug information to. | + + +## reactor.debug.argument +```elixir +argument name, source \ nil +``` + + +Specifies an argument to a Reactor step. + +Each argument is a value which is either the result of another step, or an input value. + +Individual arguments can be transformed with an arbitrary function before +being passed to any steps. + + + + +### Examples +``` +argument :name, input(:name) + +``` + +``` +argument :year, input(:date, [:year]) + +``` + +``` +argument :user, result(:create_user) + +``` + +``` +argument :user_id, result(:create_user) do + transform & &1.id +end + +``` + +``` +argument :user_id, result(:create_user, [:id]) + +``` + +``` +argument :three, value(3) + +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | The name of the argument which will be used as the key in the `arguments` map passed to the implementation. | +| `source`* | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` | | What to use as the source of the argument. See `Reactor.Dsl.Argument` for more information. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `transform` | `(any -> any) \| module \| nil` | | An optional transformation function which can be used to modify the argument before it is passed to the step. | + + + + + +### Introspection + +Target: `Reactor.Dsl.Argument` + +## reactor.debug.wait_for +```elixir +wait_for names +``` + + +Wait for the named step to complete before allowing this one to start. + +Desugars to `argument :_, result(step_to_wait_for)` + + + + +### Examples +``` +wait_for :create_user +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `names`* | `list(atom) \| atom` | | The name of the step to wait for. | + + + + + + +### Introspection + +Target: `Reactor.Dsl.WaitFor` + + + + +### Introspection + +Target: `Reactor.Dsl.Debug` + +## reactor.group +```elixir +group name +``` + + +Call functions before and after a group of steps. + + +### Nested DSLs + * [argument](#reactor-group-argument) + * [wait_for](#reactor-group-wait_for) + + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | A unique name for the group of steps. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `before_all`* | `(any, any, any -> any) \| mfa` | | The before function. See `Reactor.Step.Group` for more information. | +| `after_all`* | `(any, any, any -> any) \| mfa` | | The after function. See `Reactor.Step.Group` for more information. | +| `allow_async?` | `boolean` | `true` | Whether the emitted steps should be allowed to run asynchronously. | + + +## reactor.group.argument +```elixir +argument name, source \ nil +``` + + +Specifies an argument to a Reactor step. + +Each argument is a value which is either the result of another step, or an input value. + +Individual arguments can be transformed with an arbitrary function before +being passed to any steps. + + + + +### Examples +``` +argument :name, input(:name) + +``` + +``` +argument :year, input(:date, [:year]) + +``` + +``` +argument :user, result(:create_user) + +``` + +``` +argument :user_id, result(:create_user) do + transform & &1.id +end + +``` + +``` +argument :user_id, result(:create_user, [:id]) + +``` + +``` +argument :three, value(3) + +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | The name of the argument which will be used as the key in the `arguments` map passed to the implementation. | +| `source`* | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` | | What to use as the source of the argument. See `Reactor.Dsl.Argument` for more information. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `transform` | `(any -> any) \| module \| nil` | | An optional transformation function which can be used to modify the argument before it is passed to the step. | + + + + + +### Introspection + +Target: `Reactor.Dsl.Argument` + +## reactor.group.wait_for +```elixir +wait_for names +``` + + +Wait for the named step to complete before allowing this one to start. + +Desugars to `argument :_, result(step_to_wait_for)` + + + + +### Examples +``` +wait_for :create_user +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `names`* | `list(atom) \| atom` | | The name of the step to wait for. | + + + + + + +### Introspection + +Target: `Reactor.Dsl.WaitFor` + + + + +### Introspection + +Target: `Reactor.Dsl.Group` + +## reactor.input +```elixir +input name +``` + + +Specifies an input to the Reactor. + +An input is a value passed in to the Reactor when executing. +If a Reactor were a function, these would be it's arguments. + +Inputs can be transformed with an arbitrary function before being passed +to any steps. + + + + +### Examples +``` +input :name + +``` + +``` +input :age do + transform &String.to_integer/1 +end + +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | A unique name for this input. Used to allow steps to depend on it. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `transform` | `(any -> any) \| module \| nil` | | An optional transformation function which can be used to modify the input before it is passed to any steps. | + + + + + +### Introspection + +Target: `Reactor.Dsl.Input` + +## reactor.step +```elixir +step name, impl \ nil +``` + + +Specifies a Reactor step. + +Steps are the unit of work in a Reactor. Reactor will calculate the +dependencies graph between the steps and execute as many as it can in each +iteration. + +See the `Reactor.Step` behaviour for more information. + + +### Nested DSLs + * [argument](#reactor-step-argument) + * [wait_for](#reactor-step-wait_for) + + +### Examples +``` +step :create_user, MyApp.Steps.CreateUser do + argument :username, input(:username) + argument :password_hash, result(:hash_password) +end + +``` + +``` +step :hash_password do + argument :password, input(:password) + + run fn %{password: password}, _ -> + {:ok, Bcrypt.hash_pwd_salt(password)} + end +end + +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | A unique name for the step. Used when choosing the return value of the Reactor and for arguments into other steps. | +| `impl` | `module \| nil` | | A module that implements the `Reactor.Step` behaviour that provides the implementation. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `run` | `(any -> any) \| mfa \| (any, any -> any) \| mfa` | | Provide an anonymous function which implements the `run/3` callback. Cannot be provided at the same time as the `impl` argument. | +| `undo` | `(any -> any) \| mfa \| (any, any -> any) \| mfa \| (any, any, any -> any) \| mfa` | | Provide an anonymous function which implements the `undo/4` callback. Cannot be provided at the same time as the `impl` argument. | +| `compensate` | `(any -> any) \| mfa \| (any, any -> any) \| mfa \| (any, any, any -> any) \| mfa` | | Provide an anonymous function which implements the `undo/4` callback. Cannot be provided at the same time as the `impl` argument. | +| `max_retries` | `:infinity \| non_neg_integer` | `:infinity` | The maximum number of times that the step can be retried before failing. Only used when the result of the `compensate/4` callback is `:retry`. | +| `async?` | `boolean` | `true` | When set to true the step will be executed asynchronously via Reactor's `TaskSupervisor`. | +| `transform` | `(any -> any) \| module \| nil` | | An optional transformation function which can be used to modify the entire argument map before it is passed to the step. | + + +## reactor.step.argument +```elixir +argument name, source \ nil +``` + + +Specifies an argument to a Reactor step. + +Each argument is a value which is either the result of another step, or an input value. + +Individual arguments can be transformed with an arbitrary function before +being passed to any steps. + + + + +### Examples +``` +argument :name, input(:name) + +``` + +``` +argument :year, input(:date, [:year]) + +``` + +``` +argument :user, result(:create_user) + +``` + +``` +argument :user_id, result(:create_user) do + transform & &1.id +end + +``` + +``` +argument :user_id, result(:create_user, [:id]) + +``` + +``` +argument :three, value(3) + +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | The name of the argument which will be used as the key in the `arguments` map passed to the implementation. | +| `source`* | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` | | What to use as the source of the argument. See `Reactor.Dsl.Argument` for more information. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `transform` | `(any -> any) \| module \| nil` | | An optional transformation function which can be used to modify the argument before it is passed to the step. | + + + + + +### Introspection + +Target: `Reactor.Dsl.Argument` + +## reactor.step.wait_for +```elixir +wait_for names +``` + + +Wait for the named step to complete before allowing this one to start. + +Desugars to `argument :_, result(step_to_wait_for)` + + + + +### Examples +``` +wait_for :create_user +``` + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `names`* | `list(atom) \| atom` | | The name of the step to wait for. | + + + + + + +### Introspection + +Target: `Reactor.Dsl.WaitFor` + + + + +### Introspection + +Target: `Reactor.Dsl.Step` + +## reactor.switch +```elixir +switch name +``` + + +Use a predicate to determine which steps should be executed. + + +### Nested DSLs + * [matches?](#reactor-switch-matches?) + + * [default](#reactor-switch-default) + + + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `name`* | `atom` | | A unique name for the switch. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `on`* | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` | | The value to match against. | +| `allow_async?` | `boolean` | `true` | Whether the emitted steps should be allowed to run asynchronously. | + + +## reactor.switch.matches? +```elixir +matches? predicate +``` + + +A group of steps to run when the predicate matches. + + + + + + +### Arguments +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `predicate`* | `(any -> any) \| mfa` | | A one-arity function which is used to match the switch input. If the switch returns a truthy value, then the nested steps will be run. | +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `allow_async?` | `boolean` | `true` | Whether the emitted steps should be allowed to run asynchronously. | +| `return` | `atom` | | Specify which step result to return upon completion. | + + + + + +### Introspection + +Target: `Reactor.Dsl.Switch.Match` + +## reactor.switch.default + + +If none of the `matches?` branches match the input, then the `default` +steps will be run if provided. + + + + + + + +### Options +| Name | Type | Default | Docs | +| --- | --- | --- | --- | +| `return` | `atom` | | Specify which step result to return upon completion. | + + + + + +### Introspection + +Target: `Reactor.Dsl.Switch.Default` + + + + +### Introspection + +Target: `Reactor.Dsl.Switch` + + + + diff --git a/lib/reactor.ex b/lib/reactor.ex index e91f5a8..967251b 100644 --- a/lib/reactor.ex +++ b/lib/reactor.ex @@ -34,20 +34,6 @@ defmodule Reactor do ...> {:ok, reactor} = Builder.return(reactor, :greet) ...> Reactor.run(reactor, %{whom: nil}) {:ok, "Hello, World!"} - - - - ## DSL Documentation - - ### Index - - #{Spark.Dsl.Extension.doc_index(Dsl.sections())} - - ### Docs - - #{Spark.Dsl.Extension.doc(Dsl.sections())} - - """ defstruct context: %{}, diff --git a/lib/reactor/dsl/argument.ex b/lib/reactor/dsl/argument.ex index cb95a34..64f6de1 100644 --- a/lib/reactor/dsl/argument.ex +++ b/lib/reactor/dsl/argument.ex @@ -160,17 +160,14 @@ defmodule Reactor.Dsl.Argument do type: :atom, required: true, doc: """ - The name of the argument which will be used as the key in the - `arguments` map passed to the implementation. + The name of the argument which will be used as the key in the `arguments` map passed to the implementation. """ ], source: [ type: Template.type(), required: true, doc: """ - What to use as the source of the argument. - - See `Reactor.Dsl.Argument` for more information. + What to use as the source of the argument. See `Reactor.Dsl.Argument` for more information. """ ], transform: [ @@ -178,8 +175,7 @@ defmodule Reactor.Dsl.Argument do required: false, default: nil, doc: """ - An optional transformation function which can be used to modify the - argument before it is passed to the step. + An optional transformation function which can be used to modify the argument before it is passed to the step. """ ] ] diff --git a/lib/reactor/dsl/around.ex b/lib/reactor/dsl/around.ex index b1fa760..9e49280 100644 --- a/lib/reactor/dsl/around.ex +++ b/lib/reactor/dsl/around.ex @@ -46,9 +46,7 @@ defmodule Reactor.Dsl.Around do type: {:mfa_or_fun, 4}, required: true, doc: """ - The around function. - - See `Reactor.Step.Around` for more information. + The around function. See `Reactor.Step.Around` for more information. """ ], allow_async?: [ @@ -57,8 +55,6 @@ defmodule Reactor.Dsl.Around do default: false, doc: """ Whether the emitted steps should be allowed to run asynchronously. - - Passed to the child Reactor as it's `async?` option. """ ] ] diff --git a/lib/reactor/dsl/collect.ex b/lib/reactor/dsl/collect.ex index e532e3e..1b6e546 100644 --- a/lib/reactor/dsl/collect.ex +++ b/lib/reactor/dsl/collect.ex @@ -50,9 +50,7 @@ defmodule Reactor.Dsl.Collect do type: :atom, required: true, doc: """ - A unique name for the step. - - This is used when choosing the return value of the Reactor and for arguments into other steps. + A unique name for the step. Used when choosing the return value of the Reactor and for arguments into other steps. """ ], transform: [ @@ -60,8 +58,7 @@ defmodule Reactor.Dsl.Collect do required: false, default: nil, doc: """ - An optional transformation function which can be used to modify the - entire argument map before it is returned. + An optional transformation function which can be used to modify the entire argument map before it is returned. """ ] ] diff --git a/lib/reactor/dsl/compose.ex b/lib/reactor/dsl/compose.ex index 65a43a6..3560dd4 100644 --- a/lib/reactor/dsl/compose.ex +++ b/lib/reactor/dsl/compose.ex @@ -34,10 +34,7 @@ defmodule Reactor.Dsl.Compose do type: :atom, required: true, doc: """ - A unique name for the step. - - Allows the result of the composed reactor to be depended upon by steps - in this reactor. + A unique name for the step. Allows the result of the composed reactor to be depended upon by steps in this reactor. """ ], reactor: [ diff --git a/lib/reactor/dsl/group.ex b/lib/reactor/dsl/group.ex index 9739d01..82fb568 100644 --- a/lib/reactor/dsl/group.ex +++ b/lib/reactor/dsl/group.ex @@ -48,18 +48,14 @@ defmodule Reactor.Dsl.Group do type: {:mfa_or_fun, 3}, required: true, doc: """ - The before function. - - See `Reactor.Step.Group` for more information. + The before function. See `Reactor.Step.Group` for more information. """ ], after_all: [ type: {:mfa_or_fun, 3}, required: true, doc: """ - The after function. - - See `Reactor.Step.Group` for more information. + The after function. See `Reactor.Step.Group` for more information. """ ], allow_async?: [ @@ -68,8 +64,6 @@ defmodule Reactor.Dsl.Group do default: true, doc: """ Whether the emitted steps should be allowed to run asynchronously. - - Passed to the child Reactor as it's `async?` option. """ ] ] diff --git a/lib/reactor/dsl/input.ex b/lib/reactor/dsl/input.ex index d5a5d2c..d610d30 100644 --- a/lib/reactor/dsl/input.ex +++ b/lib/reactor/dsl/input.ex @@ -44,9 +44,7 @@ defmodule Reactor.Dsl.Input do type: :atom, required: true, doc: """ - A unique name for this input. - - The name is used to allow steps to depend on it. + A unique name for this input. Used to allow steps to depend on it. """ ], transform: [ @@ -54,8 +52,7 @@ defmodule Reactor.Dsl.Input do required: false, default: nil, doc: """ - An optional transformation function which can be used to modify the - input before it is passed to any steps. + An optional transformation function which can be used to modify the input before it is passed to any steps. """ ] ] diff --git a/lib/reactor/dsl/step.ex b/lib/reactor/dsl/step.ex index 26b64d0..bf3c3b4 100644 --- a/lib/reactor/dsl/step.ex +++ b/lib/reactor/dsl/step.ex @@ -76,47 +76,35 @@ defmodule Reactor.Dsl.Step do type: :atom, required: true, doc: """ - A unique name for the step. - - This is used when choosing the return value of the Reactor and for arguments into - other steps. + A unique name for the step. Used when choosing the return value of the Reactor and for arguments into other steps. """ ], impl: [ type: {:or, [{:spark_behaviour, Step}, nil]}, required: false, doc: """ - The step implementation. - - Provides an implementation for the step with the named module. The - module must implement the `Reactor.Step` behaviour. + A module that implements the `Reactor.Step` behaviour that provides the implementation. """ ], run: [ type: {:or, [{:mfa_or_fun, 1}, {:mfa_or_fun, 2}]}, required: false, doc: """ - Provide an anonymous function which implements the `run/3` callback. - - You cannot provide this option at the same time as the `impl` argument. + Provide an anonymous function which implements the `run/3` callback. Cannot be provided at the same time as the `impl` argument. """ ], undo: [ type: {:or, [{:mfa_or_fun, 1}, {:mfa_or_fun, 2}, {:mfa_or_fun, 3}]}, required: false, doc: """ - Provide an anonymous function which implements the `undo/4` callback. - - You cannot provide this option at the same time as the `impl` argument. + Provide an anonymous function which implements the `undo/4` callback. Cannot be provided at the same time as the `impl` argument. """ ], compensate: [ type: {:or, [{:mfa_or_fun, 1}, {:mfa_or_fun, 2}, {:mfa_or_fun, 3}]}, required: false, doc: """ - Provide an anonymous function which implements the `undo/4` callback. - - You cannot provide this option at the same time as the `impl` argument. + Provide an anonymous function which implements the `undo/4` callback. Cannot be provided at the same time as the `impl` argument. """ ], max_retries: [ @@ -124,10 +112,7 @@ defmodule Reactor.Dsl.Step do required: false, default: :infinity, doc: """ - The maximum number of times that the step can be retried before failing. - - This is only used when the result of the `compensate/4` callback is - `:retry`. + The maximum number of times that the step can be retried before failing. Only used when the result of the `compensate/4` callback is `:retry`. """ ], async?: [ @@ -135,8 +120,7 @@ defmodule Reactor.Dsl.Step do required: false, default: true, doc: """ - When set to true the step will be executed asynchronously via Reactor's - `TaskSupervisor`. + When set to true the step will be executed asynchronously via Reactor's `TaskSupervisor`. """ ], transform: [ @@ -144,8 +128,7 @@ defmodule Reactor.Dsl.Step do required: false, default: nil, doc: """ - An optional transformation function which can be used to modify the - entire argument map before it is passed to the step. + An optional transformation function which can be used to modify the entire argument map before it is passed to the step. """ ] ] diff --git a/lib/reactor/dsl/switch.ex b/lib/reactor/dsl/switch.ex index ab013f4..a44a73f 100644 --- a/lib/reactor/dsl/switch.ex +++ b/lib/reactor/dsl/switch.ex @@ -43,9 +43,7 @@ defmodule Reactor.Dsl.Switch do type: {:mfa_or_fun, 1}, required: true, doc: """ - A one-arity function which is used to match the switch input. - - If the switch returns a truthy value, then the nested steps will be run. + A one-arity function which is used to match the switch input. If the switch returns a truthy value, then the nested steps will be run. """ ], allow_async?: [ diff --git a/mix.exs b/mix.exs index 804d38a..dcc32b4 100644 --- a/mix.exs +++ b/mix.exs @@ -99,13 +99,20 @@ defmodule Reactor.MixProject do [ sobelow: "sobelow --skip", credo: "credo --strict", - "spark.formatter": "spark.formatter --extensions Reactor.Dsl" + docs: [ + "spark.cheat_sheets", + "docs", + "spark.cheat_sheets_in_search" + ], + "spark.formatter": "spark.formatter --extensions Reactor.Dsl", + "spark.cheat_sheets": "spark.cheat_sheets --extensions Reactor.Dsl", + "spark.cheat_sheets_in_search": "spark.cheat_sheets_in_search --extensions Reactor.Dsl" ] end defp extra_documentation do ["README.md"] - |> Enum.concat(Path.wildcard("documentation/**/*.md")) + |> Enum.concat(Path.wildcard("documentation/**/*.{md,livemd,cheatmd}")) |> Enum.map(fn "README.md" -> {:"README.md", title: "Read Me", ash_hq?: false} @@ -115,27 +122,16 @@ defmodule Reactor.MixProject do "documentation/topics/" <> _ = path -> {String.to_atom(path), []} + + "documentation/dsls/" <> _ = path -> + {String.to_atom(path), []} end) end defp extra_documentation_groups do - "documentation/*" - |> Path.wildcard() - |> Enum.filter(&File.dir?/1) - |> Enum.map(fn dir -> - name = - dir - |> Path.basename() - |> String.split(~r/_+/) - |> Enum.join(" ") - |> String.capitalize() - - contents = - dir - |> Path.join("**") - |> Path.wildcard() - - {name, contents} - end) + [ + Tutorials: ~r'documentation/tutorials', + DSLs: ~r'documentation/dsls' + ] end end diff --git a/mix.lock b/mix.lock index fbb9a79..3d9d01c 100644 --- a/mix.lock +++ b/mix.lock @@ -4,7 +4,7 @@ "decimal": {:hex, :decimal, "2.1.1", "5611dca5d4b2c3dd497dec8f68751f1f1a54755e8ed2a966c2633cf885973ad6", [:mix], [], "hexpm", "53cfe5f497ed0e7771ae1a475575603d77425099ba5faef9394932b35020ffcc"}, "dialyxir": {:hex, :dialyxir, "1.4.1", "a22ed1e7bd3a3e3f197b68d806ef66acb61ee8f57b3ac85fc5d57354c5482a93", [:mix], [{:erlex, ">= 0.2.6", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "84b795d6d7796297cca5a3118444b80c7d94f7ce247d49886e7c291e1ae49801"}, "doctor": {:hex, :doctor, "0.21.0", "20ef89355c67778e206225fe74913e96141c4d001cb04efdeba1a2a9704f1ab5", [:mix], [{:decimal, "~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}], "hexpm", "a227831daa79784eb24cdeedfa403c46a4cb7d0eab0e31232ec654314447e4e0"}, - "earmark_parser": {:hex, :earmark_parser, "1.4.33", "3c3fd9673bb5dcc9edc28dd90f50c87ce506d1f71b70e3de69aa8154bc695d44", [:mix], [], "hexpm", "2d526833729b59b9fdb85785078697c72ac5e5066350663e5be6a1182da61b8f"}, + "earmark_parser": {:hex, :earmark_parser, "1.4.36", "487ea8ef9bdc659f085e6e654f3c3feea1d36ac3943edf9d2ef6c98de9174c13", [:mix], [], "hexpm", "a524e395634bdcf60a616efe77fd79561bec2e930d8b82745df06ab4e844400a"}, "erlex": {:hex, :erlex, "0.2.6", "c7987d15e899c7a2f34f5420d2a2ea0d659682c06ac607572df55a43753aa12e", [:mix], [], "hexpm", "2ed2e25711feb44d52b17d2780eabf998452f6efda104877a3881c2f8c0c0c75"}, "ex_check": {:hex, :ex_check, "0.15.0", "074b94c02de11c37bba1ca82ae5cc4926e6ccee862e57a485b6ba60fca2d8dc1", [:mix], [], "hexpm", "33848031a0c7e4209c3b4369ce154019788b5219956220c35ca5474299fb6a0e"}, "ex_doc": {:hex, :ex_doc, "0.30.6", "5f8b54854b240a2b55c9734c4b1d0dd7bdd41f71a095d42a70445c03cf05a281", [:mix], [{:earmark_parser, "~> 1.4.31", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "bd48f2ddacf4e482c727f9293d9498e0881597eae6ddc3d9562bd7923375109f"}, @@ -22,7 +22,7 @@ "nimble_options": {:hex, :nimble_options, "1.0.2", "92098a74df0072ff37d0c12ace58574d26880e522c22801437151a159392270e", [:mix], [], "hexpm", "fd12a8db2021036ce12a309f26f564ec367373265b53e25403f0ee697380f1b8"}, "nimble_parsec": {:hex, :nimble_parsec, "1.3.1", "2c54013ecf170e249e9291ed0a62e5832f70a476c61da16f6aac6dca0189f2af", [:mix], [], "hexpm", "2682e3c0b2eb58d90c6375fc0cc30bc7be06f365bf72608804fb9cffa5e1b167"}, "sobelow": {:hex, :sobelow, "0.13.0", "218afe9075904793f5c64b8837cc356e493d88fddde126a463839351870b8d1e", [:mix], [{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "cd6e9026b85fc35d7529da14f95e85a078d9dd1907a9097b3ba6ac7ebbe34a0d"}, - "sourceror": {:hex, :sourceror, "0.13.0", "c6ecc96ee3ae0e042e9082a9550a1989ea40182492dc29024a8d9d2b136e5014", [:mix], [], "hexpm", "d0a819491061cd26bfa4450d1c84301a410c19c1782a6577ce15853fc0e7e4e1"}, + "sourceror": {:hex, :sourceror, "0.14.0", "b6b8552d0240400d66b6f107c1bab7ac1726e998efc797f178b7b517e928e314", [:mix], [], "hexpm", "809c71270ad48092d40bbe251a133e49ae229433ce103f762a2373b7a10a8d8b"}, "spark": {:hex, :spark, "1.1.39", "f143b84a5b796bf2d83ec8fb4793ee9e66e67510c40d785f9a67050bb88e7677", [:mix], [{:jason, "~> 1.4", [hex: :jason, repo: "hexpm", optional: false]}, {:nimble_options, "~> 0.5 or ~> 1.0", [hex: :nimble_options, repo: "hexpm", optional: false]}, {:sourceror, "~> 0.1", [hex: :sourceror, repo: "hexpm", optional: false]}], "hexpm", "d71bc26014c7e7abcdcf553f4cf7c5a5ff96f8365b1e20be3768ce503aafb203"}, "yamerl": {:hex, :yamerl, "0.10.0", "4ff81fee2f1f6a46f1700c0d880b24d193ddb74bd14ef42cb0bcf46e81ef2f8e", [:rebar3], [], "hexpm", "346adb2963f1051dc837a2364e4acf6eb7d80097c0f53cbdc3046ec8ec4b4e6e"}, "yaml_elixir": {:hex, :yaml_elixir, "2.9.0", "9a256da867b37b8d2c1ffd5d9de373a4fda77a32a45b452f1708508ba7bbcb53", [:mix], [{:yamerl, "~> 0.10", [hex: :yamerl, repo: "hexpm", optional: false]}], "hexpm", "0cb0e7d4c56f5e99a6253ed1a670ed0e39c13fc45a6da054033928607ac08dfc"},