docs: update hexdocs with new spark dsl tools (#59)

lib/reactor.ex

@@ -34,20 +34,6 @@ defmodule Reactor do
       ...> {:ok, reactor} = Builder.return(reactor, :greet)
       ...> Reactor.run(reactor, %{whom: nil})
       {:ok, "Hello, World!"}
-
-  <!--- ash-hq-hide-start --> <!--- -->
-
-  ## DSL Documentation
-
-  ### Index
-
-  #{Spark.Dsl.Extension.doc_index(Dsl.sections())}
-
-  ### Docs
-
-  #{Spark.Dsl.Extension.doc(Dsl.sections())}
-
-  <!--- ash-hq-hide-stop --> <!--- -->
   """
 
   defstruct context: %{},

lib/reactor/dsl/argument.ex

@@ -160,26 +160,22 @@ 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: [
           type: {:or, [{:spark_function_behaviour, Step, {Step.Transform, 1}}, nil]},
           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.
           """
         ]
       ]

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.
           """
         ]
       ]

lib/reactor/dsl/collect.ex

@@ -50,18 +50,15 @@ 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: [
           type: {:or, [{:spark_function_behaviour, Step, {Step.TransformAll, 1}}, nil]},
           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.
           """
         ]
       ]

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: [

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.
           """
         ]
       ]

lib/reactor/dsl/input.ex

@@ -44,18 +44,15 @@ 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: [
           type: {:or, [{:spark_function_behaviour, Step, {Step.Transform, 1}}, nil]},
           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.
           """
         ]
       ]

lib/reactor/dsl/step.ex

@@ -76,76 +76,59 @@ 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: [
           type: {:or, [{:in, [:infinity]}, :non_neg_integer]},
           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?: [
           type: :boolean,
           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: [
           type: {:or, [{:spark_function_behaviour, Step, {Step.TransformAll, 1}}, nil]},
           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.
           """
         ]
       ]

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?: [

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

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"},