From 0129285340bb4657c6a0fc8b23610722af647705 Mon Sep 17 00:00:00 2001 From: Zach Daniel Date: Mon, 8 Jul 2024 17:15:52 -0400 Subject: [PATCH] improvement: update getting started guide and document generators --- README.md | 1 + .../topics/development/generators.md | 16 +++++++ documentation/tutorials/get-started.md | 48 +++++++++++++++++++ lib/mix/tasks/gen/ash.gen.base_resource.ex | 6 ++- lib/mix/tasks/gen/ash.gen.domain.ex | 6 ++- lib/mix/tasks/gen/ash.gen.enum.ex | 6 ++- lib/mix/tasks/gen/ash.gen.resource.ex | 17 +++++-- lib/mix/tasks/patch/ash.patch.extend.ex | 24 +++++++++- mix.exs | 1 + 9 files changed, 117 insertions(+), 8 deletions(-) create mode 100644 documentation/topics/development/generators.md diff --git a/README.md b/README.md index b59c2608..a191788d 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,7 @@ Welcome! Here you will find everything you need to know to get started with and ### Development - [Project Structure](documentation/topics/development/project-structure.md) +- [Generators](documentation/topics/development/generators.md) - [Testing](documentation/topics/development/testing.md) - [Development Utilities](documentation/topics/development/development-utilities.md) - [Upgrading to 3.0](documentation/topics/development/upgrading-to-3.0.md) diff --git a/documentation/topics/development/generators.md b/documentation/topics/development/generators.md new file mode 100644 index 00000000..25e491a3 --- /dev/null +++ b/documentation/topics/development/generators.md @@ -0,0 +1,16 @@ +# Generators + +Ash comes with multiple generators, packages as mix tasks, to help you generate and make modifications to your applications. + +See the documentation for each mix task for more information. What is presented here is merely an overview. + +## Generators + +- `mix ash.gen.resource` - Generates a new `Ash.Resource` +- `mix ash.gen.domain` - Generates a new `Ash.Domain` +- `mix ash.gen.enum` - Generates a new `Ash.Type.Enum` +- `mix ash.gen.base_resource` - Generates a new base resource. + +## Patchers + +- `mix ash.patch.extend` - Adds an extension or extensions to a domain or resource. diff --git a/documentation/tutorials/get-started.md b/documentation/tutorials/get-started.md index de602fd4..0edaefc7 100644 --- a/documentation/tutorials/get-started.md +++ b/documentation/tutorials/get-started.md @@ -40,6 +40,54 @@ The actions we will be able to take on these resources include: ### Create a new project +#### Using Igniter + +First, to use `mix igniter.new`, the archive must be installed. + +To install it, run + +```bash +mix archive.install hex igniter_new +``` + +Then, create a new project: + +```elixir +mix igniter.new helpdesk --install ash && cd helpdesk +``` + +It is a good idea to make it a git repository and commit the initial project. You'll be able to see what changes we made, and can save your changes once we're done. + +```bash +# Run in your terminal +git init +git add -A +git commit -m "first commit" +git branch -M main +``` + +Open the project in your text editor, and we'll get started. + +You can skip to [Building your first Ash Domain](#building-your-first-ash-domain). + +> ### Want to skip to the end? {: .warning} +> +> Add the `--example` flag to get the example code add directly to your app! +> +> ```bash +> mix igniter.new helpdesk --install ash --example +> ``` +> +> Already know you want to use `AshPostgres`? Use the `--extend` argument. +> +> ```bash +> mix igniter.new helpdesk --install ash --example --extend postgres` +> ``` +> +> If you generate this code, you can browse the rest of the guide, but the code shown will already be present in your application 🥳 + +#### Using Mix + We first create a new project with the `--sup` flag to add a supervision tree. This will be necessary for other follow-up tutorials. ```bash diff --git a/lib/mix/tasks/gen/ash.gen.base_resource.ex b/lib/mix/tasks/gen/ash.gen.base_resource.ex index bc20ef55..f7101534 100644 --- a/lib/mix/tasks/gen/ash.gen.base_resource.ex +++ b/lib/mix/tasks/gen/ash.gen.base_resource.ex @@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.BaseResource do @moduledoc """ Generates a base resource - For example: `mix ash.gen.base_resource The.Resource.Name` + ## Example + + ```bash + mix ash.gen.base_resource MyApp.Resource + ``` """ @shortdoc "Generates a base resource. This is a module that you can use instead of `Ash.Resource`, for consistency." use Igniter.Mix.Task diff --git a/lib/mix/tasks/gen/ash.gen.domain.ex b/lib/mix/tasks/gen/ash.gen.domain.ex index 7cbc909a..424a2b9a 100644 --- a/lib/mix/tasks/gen/ash.gen.domain.ex +++ b/lib/mix/tasks/gen/ash.gen.domain.ex @@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.Domain do @moduledoc """ Generates an Ash.Domain - For example: `mix ash.gen.domain The.Domain` + ## Example + + ```bash + mix ash.gen.domain MyApp.Accounts + ``` """ @shortdoc "Generates an Ash.Domain" diff --git a/lib/mix/tasks/gen/ash.gen.enum.ex b/lib/mix/tasks/gen/ash.gen.enum.ex index b068457a..bfa906d3 100644 --- a/lib/mix/tasks/gen/ash.gen.enum.ex +++ b/lib/mix/tasks/gen/ash.gen.enum.ex @@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.Enum do @moduledoc """ Generates an Ash.Type.Enum - For example `mix ash.gen.enum The.Enum.Name list,of,values` + ## Example + + ```bash + mix ash.gen.enum MyApp.Support.Ticket.Types.Status open,closed --short-name ticket_status + ``` ## Options diff --git a/lib/mix/tasks/gen/ash.gen.resource.ex b/lib/mix/tasks/gen/ash.gen.resource.ex index d5832b54..38489971 100644 --- a/lib/mix/tasks/gen/ash.gen.resource.ex +++ b/lib/mix/tasks/gen/ash.gen.resource.ex @@ -1,11 +1,20 @@ defmodule Mix.Tasks.Ash.Gen.Resource do @moduledoc """ - Generate and configures an Ash.Resource. - - ## What changes take place? + Generate and configure an Ash.Resource. If the domain does not exist, we create it. If it does, we add the resource to it if it is not already present. + ## Example + + ```bash + mix ash.gen.resource Helpdesk.Support.Ticket \ + --default-actions read + --uuid-primary-key id + --attribute subject:string:required:public + --relationship belongs_to:representative:Helpdesk.Support.Representative \ + --extend postgres,graphql + ``` + ## Options * `--attribute` or `-a` - An attribute or comma separated list of attributes to add, as `name:type`. Modifiers: `primary_key`, `public`, and `required`. i.e `-a name:string:required` @@ -18,7 +27,7 @@ defmodule Mix.Tasks.Ash.Gen.Resource do * `--base` or `-b` - The base module to use for the resource. i.e `-b Ash.Resource`. Requires that the module is in `config :your_app, :base_resources` """ - @shortdoc "Generate an Ash.Resource." + @shortdoc "Generate and configure an Ash.Resource." use Igniter.Mix.Task @impl Igniter.Mix.Task diff --git a/lib/mix/tasks/patch/ash.patch.extend.ex b/lib/mix/tasks/patch/ash.patch.extend.ex index 1fd1c781..5542c30c 100644 --- a/lib/mix/tasks/patch/ash.patch.extend.ex +++ b/lib/mix/tasks/patch/ash.patch.extend.ex @@ -2,7 +2,29 @@ defmodule Mix.Tasks.Ash.Patch.Extend do @moduledoc """ Adds an extension or extensions to the domain/resource - For example: `mix ash.patch.extend My.Domain.Resource Ash.Policy.Authorizer` + Extensions can either be a fully qualified module name, or one of the following list, based on the thing being extended + + ### Ash.Domain + + - `json_api` - `AshJsonApi.Domain` + - `graphql` - `AshGraphql.Domain` + + ### Ash.Resource + + - `postgres` - `AshPostgres.DataLayer` + - `sqlite` - `AshSqlite.DataLayer` + - `mysql` - `AshMysql.DataLayer` + - `ets` - `Ash.DataLayer.Ets` + - `mnesia` - `Ash.DataLayer.Mnesia` + - `embedded` - `data_layer: :embedded` + - `json_api` - `AshJsonApi.Resource` + - `graphql` - `AshGraphql.Resource` + + ## Example + + ```bash + mix ash.patch.extend My.Domain.Resource postgres,Ash.Policy.Authorizer + ``` """ @shortdoc "Adds an extension or extensions to the given domain/resource" require Igniter.Code.Common diff --git a/mix.exs b/mix.exs index 44cbfe9f..0da571b5 100644 --- a/mix.exs +++ b/mix.exs @@ -72,6 +72,7 @@ defmodule Ash.MixProject do "documentation/topics/advanced/multitenancy.md", "documentation/topics/advanced/writing-extensions.md", "documentation/topics/development/project-structure.md", + "documentation/topics/development/generators.md", "documentation/topics/development/error-handling.md", "documentation/topics/development/testing.md", "documentation/topics/development/development-utilities.md",