From af582e51fb356818a01f45bc41bbde1aec426816 Mon Sep 17 00:00:00 2001 From: Zach Daniel Date: Fri, 12 Jan 2024 16:40:32 -0500 Subject: [PATCH] chore: update ex_doc, clean up docs --- .../dsls/DSL:-AshStateMachine.cheatmd | 266 ------------------ documentation/dsls/DSL:-AshStateMachine.md | 93 ++++++ mix.exs | 55 +--- mix.lock | 10 +- 4 files changed, 108 insertions(+), 316 deletions(-) delete mode 100644 documentation/dsls/DSL:-AshStateMachine.cheatmd create mode 100644 documentation/dsls/DSL:-AshStateMachine.md diff --git a/documentation/dsls/DSL:-AshStateMachine.cheatmd b/documentation/dsls/DSL:-AshStateMachine.cheatmd deleted file mode 100644 index 2a496c6..0000000 --- a/documentation/dsls/DSL:-AshStateMachine.cheatmd +++ /dev/null @@ -1,266 +0,0 @@ - -# DSL: AshStateMachine - -Provides tools for defining and working with resource-backed state machines. - - -## state_machine - - -### Nested DSLs - * [transitions](#state_machine-transitions) - * transition - - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - initial_states - - - * - - - list(atom) - - - - The allowed starting states of this state machine. -
- - - deprecated_states - - - - - list(atom) - - [] - - A list of states that have been deprecated but are still valid. These will still be in the possible list of states, but `:*` will not include them. - -
- - - extra_states - - - - - list(atom) - - [] - - A list of states that may be used by transitions to/from `:*`. See the docs on wildcards for more. - -
- - - state_attribute - - - - - atom - - :state - - The attribute to store the state in. -
- - - default_initial_state - - - - - atom - - - - The default initial state -
- - -## state_machine.transitions -### Wildcards -Use `:*` to represent "any action" when used in place of an action, or "any state" when used in place of a state. - -For example: - -```elixir -transition :*, from: :*, to: :* -``` - -The full list of states is derived at compile time from the transitions. -Use the `extra_states` to express that certain types should be included -in that list even though no transitions go to/from that state explicitly. -This is necessary for cases where there are states that use `:*` and no -transition explicitly leads to that transition. - - -### Nested DSLs - * [transition](#state_machine-transitions-transition) - - - - - -## state_machine.transitions.transition -```elixir -transition action -``` - - - - - - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - action - - - * - - - atom - - - - The corresponding action that is invoked for the transition. Use `:*` to allow any update action to perform this transition. -
- - - from - - - * - - - list(atom) | atom - - - - The states in which this action may be called. If not specified, then any state is accepted. Use `:*` to refer to all states. -
- - - to - - - * - - - list(atom) | atom - - - - The states that this action may move to. If not specified, then any state is accepted. Use `:*` to refer to all states. -
- - - - - -### Introspection - -Target: `AshStateMachine.Transition` - - - - - - diff --git a/documentation/dsls/DSL:-AshStateMachine.md b/documentation/dsls/DSL:-AshStateMachine.md new file mode 100644 index 0000000..fe6a6dd --- /dev/null +++ b/documentation/dsls/DSL:-AshStateMachine.md @@ -0,0 +1,93 @@ + +# DSL: AshStateMachine + +Provides tools for defining and working with resource-backed state machines. + + +## state_machine + + +### Nested DSLs + * [transitions](#state_machine-transitions) + * transition + + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`initial_states`](#state_machine-initial_states){: #state_machine-initial_states .spark-required} | `list(atom)` | | The allowed starting states of this state machine. | +| [`deprecated_states`](#state_machine-deprecated_states){: #state_machine-deprecated_states } | `list(atom)` | `[]` | A list of states that have been deprecated but are still valid. These will still be in the possible list of states, but `:*` will not include them. | +| [`extra_states`](#state_machine-extra_states){: #state_machine-extra_states } | `list(atom)` | `[]` | A list of states that may be used by transitions to/from `:*`. See the docs on wildcards for more. | +| [`state_attribute`](#state_machine-state_attribute){: #state_machine-state_attribute } | `atom` | `:state` | The attribute to store the state in. | +| [`default_initial_state`](#state_machine-default_initial_state){: #state_machine-default_initial_state } | `atom` | | The default initial state | + + +## state_machine.transitions +### Wildcards +Use `:*` to represent "any action" when used in place of an action, or "any state" when used in place of a state. + +For example: + +```elixir +transition :*, from: :*, to: :* +``` + +The full list of states is derived at compile time from the transitions. +Use the `extra_states` to express that certain types should be included +in that list even though no transitions go to/from that state explicitly. +This is necessary for cases where there are states that use `:*` and no +transition explicitly leads to that transition. + + +### Nested DSLs + * [transition](#state_machine-transitions-transition) + + + + + +## state_machine.transitions.transition +```elixir +transition action +``` + + + + + + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`action`](#state_machine-transitions-transition-action){: #state_machine-transitions-transition-action .spark-required} | `atom` | | The corresponding action that is invoked for the transition. Use `:*` to allow any update action to perform this transition. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`from`](#state_machine-transitions-transition-from){: #state_machine-transitions-transition-from .spark-required} | `list(atom) \| atom` | | The states in which this action may be called. If not specified, then any state is accepted. Use `:*` to refer to all states. | +| [`to`](#state_machine-transitions-transition-to){: #state_machine-transitions-transition-to .spark-required} | `list(atom) \| atom` | | The states that this action may move to. If not specified, then any state is accepted. Use `:*` to refer to all states. | + + + + + +### Introspection + +Target: `AshStateMachine.Transition` + + + + + + + + diff --git a/mix.exs b/mix.exs index d3c9b11..fdaea83 100644 --- a/mix.exs +++ b/mix.exs @@ -45,49 +45,6 @@ defmodule AshStateMachine.MixProject do ["lib"] end - defp extras() do - "documentation/**/*.{md,cheatmd,livemd}" - |> Path.wildcard() - |> Enum.map(fn path -> - title = - path - |> Path.basename(".md") - |> Path.basename(".cheatmd") - |> Path.basename(".livemd") - |> String.split(~r/[-_]/) - |> Enum.map(&capitalize_first/1) - |> Enum.join(" ") - |> case do - "F A Q" -> - "FAQ" - - other -> - other - end - - {String.to_atom(path), - [ - title: title - ]} - end) - end - - defp capitalize_first(string) do - [h | t] = String.graphemes(string) - String.capitalize(h) <> Enum.join(t) - end - - defp groups_for_extras() do - [ - Tutorials: [ - ~r'documentation/tutorials' - ], - "How To": ~r'documentation/how_to', - Topics: ~r'documentation/topics', - DSLs: ~r'documentation/dsls' - ] - end - defp docs do [ main: "get-started-with-state-machines", @@ -129,8 +86,16 @@ defmodule AshStateMachine.MixProject do _ -> "" end, - extras: extras(), - groups_for_extras: groups_for_extras(), + extras: [ + "documentation/tutorials/get-started-with-state-machines.md", + "documentation/dsls/DSL:-AshStateMachine.md" + ], + groups_for_extras: [ + Tutorials: ~r'documentation/tutorials', + "How To": ~r'documentation/how_to', + Topics: ~r'documentation/topics', + DSLs: ~r'documentation/dsls' + ], groups_for_modules: [ Dsl: [ AshStateMachine diff --git a/mix.lock b/mix.lock index 2f11529..474c6b1 100644 --- a/mix.lock +++ b/mix.lock @@ -6,13 +6,13 @@ "credo": {:hex, :credo, "1.7.0", "6119bee47272e85995598ee04f2ebbed3e947678dee048d10b5feca139435f75", [:mix], [{:bunt, "~> 0.2.1", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2.8", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "6839fcf63d1f0d1c0f450abc8564a57c43d644077ab96f2934563e68b8a769d7"}, "decimal": {:hex, :decimal, "2.1.1", "5611dca5d4b2c3dd497dec8f68751f1f1a54755e8ed2a966c2633cf885973ad6", [:mix], [], "hexpm", "53cfe5f497ed0e7771ae1a475575603d77425099ba5faef9394932b35020ffcc"}, "dialyxir": {:hex, :dialyxir, "1.3.0", "fd1672f0922b7648ff9ce7b1b26fcf0ef56dda964a459892ad15f6b4410b5284", [:mix], [{:erlex, ">= 0.2.6", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "00b2a4bcd6aa8db9dcb0b38c1225b7277dca9bc370b6438715667071a304696f"}, - "earmark_parser": {:hex, :earmark_parser, "1.4.36", "487ea8ef9bdc659f085e6e654f3c3feea1d36ac3943edf9d2ef6c98de9174c13", [:mix], [], "hexpm", "a524e395634bdcf60a616efe77fd79561bec2e930d8b82745df06ab4e844400a"}, + "earmark_parser": {:hex, :earmark_parser, "1.4.39", "424642f8335b05bb9eb611aa1564c148a8ee35c9c8a8bba6e129d51a3e3c6769", [:mix], [], "hexpm", "06553a88d1f1846da9ef066b87b57c6f605552cfbe40d20bd8d59cc6bde41944"}, "ecto": {:hex, :ecto, "3.10.1", "c6757101880e90acc6125b095853176a02da8f1afe056f91f1f90b80c9389822", [:mix], [{:decimal, "~> 1.6 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "d2ac4255f1601bdf7ac74c0ed971102c6829dc158719b94bd30041bbad77f87a"}, "elixir_make": {:hex, :elixir_make, "0.7.6", "67716309dc5d43e16b5abbd00c01b8df6a0c2ab54a8f595468035a50189f9169", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}], "hexpm", "5a0569756b0f7873a77687800c164cca6dfc03a09418e6fcf853d78991f49940"}, "erlex": {:hex, :erlex, "0.2.6", "c7987d15e899c7a2f34f5420d2a2ea0d659682c06ac607572df55a43753aa12e", [:mix], [], "hexpm", "2ed2e25711feb44d52b17d2780eabf998452f6efda104877a3881c2f8c0c0c75"}, "ets": {:hex, :ets, "0.8.1", "8ff9bcda5682b98493f8878fc9dbd990e48d566cba8cce59f7c2a78130da29ea", [:mix], [], "hexpm", "6be41b50adb5bc5c43626f25ea2d0af1f4a242fb3fad8d53f0c67c20b78915cc"}, "ex_check": {:hex, :ex_check, "0.12.0", "c0e2919ecc06afeaf62c52d64f3d91bd4bc7dd8deaac5f84becb6278888c967a", [:mix], [], "hexpm", "cfafa8ef97c2596d45a1f19b5794cb5c7f700f25d164d3c9f8d7ec17ee67cf42"}, - "ex_doc": {:git, "https://github.com/elixir-lang/ex_doc.git", "16a8f536d1a0868293a30d63bcff6510bf023de3", []}, + "ex_doc": {:git, "https://github.com/elixir-lang/ex_doc.git", "a663c13478a49d29ae0267b6e45badb803267cf0", []}, "excoveralls": {:hex, :excoveralls, "0.13.4", "7b0baee01fe150ef81153e6ffc0fc68214737f54570dc257b3ca4da8e419b812", [:mix], [{:hackney, "~> 1.16", [hex: :hackney, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "faae00b3eee35cdf0342c10b669a7c91f942728217d2a7c7f644b24d391e6190"}, "file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"}, "git_cli": {:hex, :git_cli, "0.3.0", "a5422f9b95c99483385b976f5d43f7e8233283a47cda13533d7c16131cb14df5", [:mix], [], "hexpm", "78cb952f4c86a41f4d3511f1d3ecb28edb268e3a7df278de2faa1bd4672eaf9b"}, @@ -25,13 +25,13 @@ "makeup_erlang": {:hex, :makeup_erlang, "0.1.2", "ad87296a092a46e03b7e9b0be7631ddcf64c790fa68a9ef5323b6cbb36affc72", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "f3f5a1ca93ce6e092d92b6d9c049bcda58a3b617a8d888f8e7231c85630e8108"}, "metrics": {:hex, :metrics, "1.0.1", "25f094dea2cda98213cecc3aeff09e940299d950904393b2a29d191c346a8486", [:rebar3], [], "hexpm", "69b09adddc4f74a40716ae54d140f93beb0fb8978d8636eaded0c31b6f099f16"}, "mimerl": {:hex, :mimerl, "1.2.0", "67e2d3f571088d5cfd3e550c383094b47159f3eee8ffa08e64106cdf5e981be3", [:rebar3], [], "hexpm", "f278585650aa581986264638ebf698f8bb19df297f66ad91b18910dfc6e19323"}, - "nimble_options": {:hex, :nimble_options, "1.0.2", "92098a74df0072ff37d0c12ace58574d26880e522c22801437151a159392270e", [:mix], [], "hexpm", "fd12a8db2021036ce12a309f26f564ec367373265b53e25403f0ee697380f1b8"}, + "nimble_options": {:hex, :nimble_options, "1.1.0", "3b31a57ede9cb1502071fade751ab0c7b8dbe75a9a4c2b5bbb0943a690b63172", [:mix], [], "hexpm", "8bbbb3941af3ca9acc7835f5655ea062111c9c27bcac53e004460dfd19008a99"}, "nimble_parsec": {:hex, :nimble_parsec, "1.3.1", "2c54013ecf170e249e9291ed0a62e5832f70a476c61da16f6aac6dca0189f2af", [:mix], [], "hexpm", "2682e3c0b2eb58d90c6375fc0cc30bc7be06f365bf72608804fb9cffa5e1b167"}, "parse_trans": {:hex, :parse_trans, "3.3.1", "16328ab840cc09919bd10dab29e431da3af9e9e7e7e6f0089dd5a2d2820011d8", [:rebar3], [], "hexpm", "07cd9577885f56362d414e8c4c4e6bdf10d43a8767abb92d24cbe8b24c54888b"}, "picosat_elixir": {:hex, :picosat_elixir, "0.2.3", "bf326d0f179fbb3b706bb2c15fbc367dacfa2517157d090fdfc32edae004c597", [:make, :mix], [{:elixir_make, "~> 0.6", [hex: :elixir_make, repo: "hexpm", optional: false]}], "hexpm", "f76c9db2dec9d2561ffaa9be35f65403d53e984e8cd99c832383b7ab78c16c66"}, "sobelow": {:hex, :sobelow, "0.12.2", "45f4d500e09f95fdb5a7b94c2838d6b26625828751d9f1127174055a78542cf5", [:mix], [{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "2f0b617dce551db651145662b84c8da4f158e7abe049a76daaaae2282df01c5d"}, - "sourceror": {:hex, :sourceror, "0.14.0", "b6b8552d0240400d66b6f107c1bab7ac1726e998efc797f178b7b517e928e314", [:mix], [], "hexpm", "809c71270ad48092d40bbe251a133e49ae229433ce103f762a2373b7a10a8d8b"}, - "spark": {:hex, :spark, "1.1.40", "b61438fece40eb0ffed7c4c9e5f1c2c817209902ed853b0008b7681b1994c29c", [: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", "40d0f803f1090249ef6a76cb2bf40466c57f4995326dc97996e0b8b4f365ad17"}, + "sourceror": {:hex, :sourceror, "0.14.1", "c6fb848d55bd34362880da671debc56e77fd722fa13b4dcbeac89a8998fc8b09", [:mix], [], "hexpm", "8b488a219e4c4d7d9ff29d16346fd4a5858085ccdd010e509101e226bbfd8efc"}, + "spark": {:hex, :spark, "1.1.54", "54dac39403a2960f738ba5d60678d20b30de7381fb51b787b6bcb6aeabb73d9d", [: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", "abc9a67cfb60a97d2f3c7e270fa968a2ace94f389e2741d406239d237ec6dbb1"}, "ssl_verify_fun": {:hex, :ssl_verify_fun, "1.1.7", "354c321cf377240c7b8716899e182ce4890c5938111a1296add3ec74cf1715df", [:make, :mix, :rebar3], [], "hexpm", "fe4c190e8f37401d30167c8c405eda19469f34577987c76dde613e838bbc67f8"}, "stream_data": {:hex, :stream_data, "0.5.0", "b27641e58941685c75b353577dc602c9d2c12292dd84babf506c2033cd97893e", [:mix], [], "hexpm", "012bd2eec069ada4db3411f9115ccafa38540a3c78c4c0349f151fc761b9e271"}, "telemetry": {:hex, :telemetry, "1.2.1", "68fdfe8d8f05a8428483a97d7aab2f268aaff24b49e0f599faa091f1d4e7f61c", [:rebar3], [], "hexpm", "dad9ce9d8effc621708f99eac538ef1cbe05d6a874dd741de2e689c47feafed5"},