docs: various documentation improvements

This commit is contained in:
Zach Daniel 2023-09-15 09:35:29 -04:00
parent c7c154dfb7
commit 24d2ecd554
5 changed files with 56 additions and 138 deletions

View file

@ -11,7 +11,8 @@
## ...or adjusted (e.g. use one-line formatter for more compact credo output)
# {:credo, "mix credo --format oneline"},
{:check_formatter, command: "mix spark.formatter --check"}
{:check_formatter, command: "mix spark.formatter --check"},
{:check_cheat_sheets, command: "mix spark.cheat_sheets --check"},
## custom new tools may be added (mix tasks or arbitrary commands)
# {:my_mix_task, command: "mix release", env: %{"MIX_ENV" => "prod"}},

View file

@ -1,91 +1,6 @@
# DSL: AshStateMachine
Functions for working with AshStateMachine.
<!--- ash-hq-hide-start --> <!--- -->
## DSL Documentation
### Index
* state_machine
* transitions
* transition
### Docs
## state_machine
* [transitions](#module-transitions)
* transition
---
* `:deprecated_states` (list of `t:atom/0`) - A list of states that have been deprecated.
The list of states is derived from the transitions normally.
Use this option to express that certain types should still
be included in the derived state list even though no transitions
go to/from that state anymore. `:*` transitions will not include
these states. The default value is `[]`.
* `:extra_states` (list of `t:atom/0`) - A list of states that may be used by transitions to/from `:*`
The list of states is derived from the transitions normally.
Use this option to express that certain types should still
be included even though no transitions go to/from that state anymore.
`:*` transitions will include these states. The default value is `[]`.
* `:state_attribute` (`t:atom/0`) - The attribute to store the state in. The default value is `:state`.
* `:initial_states` (list of `t:atom/0`) - Required. The allowed starting states of this state machine.
* `:default_initial_state` (`t:atom/0`) - The default initial state
### transitions
* [transition](#module-transition)
---
#### transition
* `:action` (`t:atom/0`) - The corresponding action that is invoked for the transition. Use `:*` to allow any update action to perform this transition.
* `:from` - Required. The states in which this action may be called. If not specified, then any state is accepted. Use `:*` to refer to all states.
* `:to` - Required. The states that this action may move to. If not specified, then any state is accepted. Use `:*` to refer to all states.
<!--- ash-hq-hide-stop --> <!--- -->
Provides tools for defining and working with resource-backed state machines.
## state_machine
@ -100,8 +15,8 @@ Functions for working with AshStateMachine.
### Options
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `deprecated_states` | `list(atom)` | [] | A list of states that have been deprecated. The list of states is derived from the transitions normally. Use this option to express that certain types should still be included in the derived state list even though no transitions go to/from that state anymore. `:*` transitions will not include these states. |
| `extra_states` | `list(atom)` | [] | A list of states that may be used by transitions to/from `:*` The list of states is derived from the transitions normally. Use this option to express that certain types should still be included even though no transitions go to/from that state anymore. `:*` transitions will include these states. |
| `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. |
| `initial_states`* | `list(atom)` | | The allowed starting states of this state machine. |
| `default_initial_state` | `atom` | | The default initial state |
@ -115,6 +30,9 @@ Functions for working with AshStateMachine.
## state_machine.transitions.transition
```elixir
transition action
```
@ -126,7 +44,7 @@ Functions for working with AshStateMachine.
### Arguments
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `action` | `atom` | | The corresponding action that is invoked for the transition. Use `:*` to allow any update action to perform this transition. |
| `action`* | `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 |
| --- | --- | --- | --- |

View file

@ -23,6 +23,7 @@ defmodule AshStateMachine do
schema: [
action: [
type: :atom,
required: true,
doc:
"The corresponding action that is invoked for the transition. Use `:*` to allow any update action to perform this transition."
],
@ -43,6 +44,20 @@ defmodule AshStateMachine do
@transitions %Spark.Dsl.Section{
name: :transitions,
describe: """
# Wildcards
Use `:*` to represent "any action" when used in place of an action, or "any state" when used in place of a state.
```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.
""",
entities: [
@transition
]
@ -55,23 +70,14 @@ defmodule AshStateMachine do
type: {:list, :atom},
default: [],
doc: """
A list of states that have been deprecated.
The list of states is derived from the transitions normally.
Use this option to express that certain types should still
be included in the derived state list even though no transitions
go to/from that state anymore. `:*` transitions will not include
these states.
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: [
type: {:list, :atom},
default: [],
doc: """
A list of states that may be used by transitions to/from `:*`
The list of states is derived from the transitions normally.
Use this option to express that certain types should still
be included even though no transitions go to/from that state anymore.
`:*` transitions will include these states.
A list of states that may be used by transitions to/from `:*`. See the docs on wildcards for more.
"""
],
state_attribute: [
@ -97,19 +103,7 @@ defmodule AshStateMachine do
@sections [@state_machine]
@moduledoc """
Functions for working with AshStateMachine.
<!--- ash-hq-hide-start --> <!--- -->
## DSL Documentation
### Index
#{Spark.Dsl.Extension.doc_index(@sections)}
### Docs
#{Spark.Dsl.Extension.doc(@sections)}
<!--- ash-hq-hide-stop --> <!--- -->
Provides tools for defining and working with resource-backed state machines.
"""
use Spark.Dsl.Extension,

41
mix.exs
View file

@ -46,12 +46,14 @@ defmodule AshStateMachine.MixProject do
end
defp extras() do
"documentation/**/*.md"
"documentation/**/*.{md,cheatmd,livemd}"
|> Path.wildcard()
|> Enum.map(fn path ->
title =
path
|> Path.basename(".md")
|> Path.basename(".livemd")
|> Path.basename(".cheatmd")
|> Path.basename(".livemd")
|> String.split(~r/[-_]/)
|> Enum.map(&String.capitalize/1)
|> Enum.join(" ")
@ -71,23 +73,19 @@ defmodule AshStateMachine.MixProject do
end
defp groups_for_extras() do
"documentation/*"
|> Path.wildcard()
|> Enum.map(fn folder ->
name =
folder
|> Path.basename()
|> String.split(~r/[-_]/)
|> Enum.map(&String.capitalize/1)
|> Enum.join(" ")
{name, folder |> Path.join("**") |> Path.wildcard()}
end)
[
Tutorials: [
~r'documentation/tutorials'
],
"How To": ~r'documentation/how_to',
Topics: ~r'documentation/topics',
DSLs: ~r'documentation/dsls'
]
end
defp docs do
[
main: "AshStateMachine",
main: "get-started-with-state-machines",
source_ref: "v#{@version}",
logo: "logos/small-logo.png",
extra_section: "GUIDES",
@ -136,7 +134,8 @@ defmodule AshStateMachine.MixProject do
defp deps do
[
{:ash, "~> 2.7"},
{:spark, ">= 1.1.22"},
# {:spark, ">= 1.1.22"},
{:spark, path: "../spark", override: true},
{:ex_doc, "~> 0.22", only: [:dev, :test], runtime: false},
{:ex_check, "~> 0.12.0", only: [:dev, :test]},
{:credo, ">= 0.0.0", only: [:dev, :test], runtime: false},
@ -151,9 +150,15 @@ defmodule AshStateMachine.MixProject do
[
sobelow: "sobelow --skip",
credo: "credo --strict",
docs: ["docs", "ash.replace_doc_links"],
docs: [
"spark.cheat_sheets",
"docs",
"ash.replace_doc_links",
"spark.cheat_sheets_in_search"
],
"spark.formatter": "spark.formatter --extensions AshStateMachine",
"spark.cheat_sheets": "spark.cheat_sheets --extensions AshStateMachine"
"spark.cheat_sheets": "spark.cheat_sheets --extensions AshStateMachine",
"spark.cheat_sheets_in_search": "spark.cheat_sheets_in_search --extensions AshStateMachine"
]
end
end

View file

@ -4,29 +4,29 @@
"certifi": {:hex, :certifi, "2.9.0", "6f2a475689dd47f19fb74334859d460a2dc4e3252a3324bd2111b8f0429e7e21", [:rebar3], [], "hexpm", "266da46bdb06d6c6d35fde799bcb28d36d985d424ad7c08b5bb48f5b5cdd4641"},
"comparable": {:hex, :comparable, "1.0.0", "bb669e91cedd14ae9937053e5bcbc3c52bb2f22422611f43b6e38367d94a495f", [:mix], [{:typable, "~> 0.1", [hex: :typable, repo: "hexpm", optional: false]}], "hexpm", "277c11eeb1cd726e7cd41c6c199e7e52fa16ee6830b45ad4cdc62e51f62eb60c"},
"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.0.0", "a78296e617b0f5dd4c6caf57c714431347912ffb1d0842e998e9792b5642d697", [:mix], [], "hexpm", "34666e9c55dea81013e77d9d87370fe6cb6291d1ef32f46a1600230b1d44f577"},
"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.31", "a93921cdc6b9b869f519213d5bc79d9e218ba768d7270d46fdcf1c01bacff9e2", [:mix], [], "hexpm", "317d367ee0335ef037a87e46c91a2269fef6306413f731e8ec11fc45a7efd059"},
"earmark_parser": {:hex, :earmark_parser, "1.4.35", "437773ca9384edf69830e26e9e7b2e0d22d2596c4a6b17094a3b29f01ea65bb8", [:mix], [], "hexpm", "8652ba3cb85608d0d7aa2d21b45c6fad4ddc9a1f9a1f1b30ca3a246f0acc33f6"},
"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": {:hex, :ex_doc, "0.29.4", "6257ecbb20c7396b1fe5accd55b7b0d23f44b6aa18017b415cb4c2b91d997729", [: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", "2c6699a737ae46cb61e4ed012af931b57b699643b24dabe2400a8168414bc4f5"},
"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"},
"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"},
"git_ops": {:hex, :git_ops, "2.5.6", "dd01e0e4aedc69b532860ae72281902b00474f4f729b64193f5350daeec191e5", [:mix], [{:git_cli, "~> 0.2", [hex: :git_cli, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "00ed67de1f83684424196823d66e0f15c26117ee2ea6a3174b84de5b030b4112"},
"hackney": {:hex, :hackney, "1.18.1", "f48bf88f521f2a229fc7bae88cf4f85adc9cd9bcf23b5dc8eb6a1788c662c4f6", [:rebar3], [{:certifi, "~> 2.9.0", [hex: :certifi, repo: "hexpm", optional: false]}, {:idna, "~> 6.1.0", [hex: :idna, repo: "hexpm", optional: false]}, {:metrics, "~> 1.0.0", [hex: :metrics, repo: "hexpm", optional: false]}, {:mimerl, "~> 1.1", [hex: :mimerl, repo: "hexpm", optional: false]}, {:parse_trans, "3.3.1", [hex: :parse_trans, repo: "hexpm", optional: false]}, {:ssl_verify_fun, "~> 1.1.0", [hex: :ssl_verify_fun, repo: "hexpm", optional: false]}, {:unicode_util_compat, "~> 0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "a4ecdaff44297e9b5894ae499e9a070ea1888c84afdd1fd9b7b2bc384950128e"},
"idna": {:hex, :idna, "6.1.1", "8a63070e9f7d0c62eb9d9fcb360a7de382448200fbbd1b106cc96d3d8099df8d", [:rebar3], [{:unicode_util_compat, "~> 0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "92376eb7894412ed19ac475e4a86f7b413c1b9fbb5bd16dccd57934157944cea"},
"jason": {:hex, :jason, "1.4.0", "e855647bc964a44e2f67df589ccf49105ae039d4179db7f6271dfd3843dc27e6", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "79a3791085b2a0f743ca04cec0f7be26443738779d09302e01318f97bdb82121"},
"jason": {:hex, :jason, "1.4.1", "af1504e35f629ddcdd6addb3513c3853991f694921b1b9368b0bd32beb9f1b63", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "fbb01ecdfd565b56261302f7e1fcc27c4fb8f32d56eab74db621fc154604a7a1"},
"makeup": {:hex, :makeup, "1.1.0", "6b67c8bc2882a6b6a445859952a602afc1a41c2e08379ca057c0f525366fc3ca", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "0a45ed501f4a8897f580eabf99a2e5234ea3e75a4373c8a52824f6e873be57a6"},
"makeup_elixir": {:hex, :makeup_elixir, "0.16.1", "cc9e3ca312f1cfeccc572b37a09980287e243648108384b97ff2b76e505c3555", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "e127a341ad1b209bd80f7bd1620a15693a9908ed780c3b763bccf7d200c767c6"},
"makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"},
"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_parsec": {:hex, :nimble_parsec, "1.3.0", "9e18a119d9efc3370a3ef2a937bf0b24c088d9c4bf0ba9d7c3751d49d347d035", [:mix], [], "hexpm", "7977f183127a7cbe9346981e2f480dc04c55ffddaef746bd58debd566070eef8"},
"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"},